diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 7352a8f422..4b3693b04f 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -20,6 +20,7 @@ Contents users developers contribute + patch-review Indices and tables ================== diff --git a/doc/guides/patch-review.rst b/doc/guides/patch-review.rst new file mode 100644 index 0000000000..86f07cb207 --- /dev/null +++ b/doc/guides/patch-review.rst @@ -0,0 +1,20 @@ +******************************* +Unikraft Patch Review Guideline +******************************* + +.. _Patchwork: https://github.com/getpatchwork/patchwork + +This is a document to better describe the patch review process and patch management using Patchwork_. The main targets group for this guideline are: + + * **Reviewers** + + * **Contributors** + +Guide +================== + +.. toctree:: + :maxdepth: 2 + + review + patchwork diff --git a/doc/guides/patchwork.rst b/doc/guides/patchwork.rst new file mode 100644 index 0000000000..a5e4f3dcc3 --- /dev/null +++ b/doc/guides/patchwork.rst @@ -0,0 +1,58 @@ +==================================== +Managing Patches using Patchwork +==================================== + +.. _Patchwork: https://patchwork.unikraft.org/project/unikraft/list/ + +Patchwork_ is a tool used for the management of sent patches, so we can see at what +stage are the patches that we have submitted. + +To use Patchwork_, the first step would be to create an account `here `__. +The first step that you need to do is to find out the series of patches that you need +to review. You can do this by clicking on the second column, **Series**, in the `patch list `_. + +.. image:: /_static/image3.png + +Suppose that the **Add clang support** series needs to be reviewed. After clicking on the +series title you will be directed to the series page. + +.. image:: /_static/image7.png + +The URL will indicate the number of series. +In our case, it is about: https://patchwork.unikraft.org/project/unikraft/list/?series=1584 +and that means your patches series is 1584. + +To get the patches locally you should configure your git. For this, you need to install `git-pw `_. + +The server and API token should be set. The server is https://patchwork.unikraft.org/ +and you can take your API token from `here `__. + +.. image:: /_static/image4.png + +To finish your configuration you shouldp use the following commands: + +.. image:: /_static/image1.png + +If the server is still not configured properly, you can also try: + +`git config pw.server "https://patchwork.unikraft.org/api/1.1"` + +Then all you need to do is to apply that series: + +.. image:: /_static/image8.png + +**Note** + +If the patches you are working on are from the Unikraft repo then you should +make the above changes to the local clone. If instead, it is a new application +or a new library then you should create a separate folder and version it with +**git init**, then apply all the above steps. +For example, if you want to apply the changes from a new library like `this `_ +you should do the following: + +.. image:: /_static/image6.png + + +.. toctree:: + :maxdepth: 2 + diff --git a/doc/guides/review.rst b/doc/guides/review.rst new file mode 100644 index 0000000000..90b5652752 --- /dev/null +++ b/doc/guides/review.rst @@ -0,0 +1,82 @@ +=========================================== +Reviewing Patches using the Mailing List +=========================================== + +.. _Patchwork: https://patchwork.unikraft.org/project/unikraft/list/ + +.. toctree:: + :maxdepth: 2 + + +######################### +Review process +######################### + +This is a section to better describe the entire review process using the `Mailing List `_. +The purpose of a review is to make sure that everything is in order with the submitted +patches and that the one who submitted the patches did not omit something that should be +included for a better structure or performance of the project. + +To be a reviewer, the first step would be to subscribe to the `Mailing List `_. + +After subscribing to the `Mailing List `_ +you will receive all the new patches submitted and you will be able to see the progress within the project. +You should only review the patches to which you are assigned. You can see this quite easily because +for these patches you are assigned in CC. + +You will see the patches in a series like this: + +.. image:: /_static/image2.png + +The mails that are numbered with 0/N represent the cover letter of the patches and mainly here +is a general description. It is not mandatory to reply to this email, only if you have +something to say in general about all the submitted patches. +After you finish the process review you should reply to all on each patch message on the +`Mailing List `_. +Place the review message at the end of each reply: + + Reviewed-by: **YOUR_NAME ** + +This is used by Patchwork_ to track the review process. + +To take the patches locally and test them you have two options: + + * You can take the content of the mail and make a .diff file that you can then apply + to the project you have configured locally. You can apply a diff file by command + **git apply** /path/to/file.diff. + * Another method is to use Patchwork_ which simplifies the process, but you need a + git configuration which will be detailed in the **Managing Patches using Patchwork** + section. + + +################################## +Responding to a non-received email +################################## + +In case you want to review a patch sent on the `Mailing List `_, +but which you don’t have in your inbox, here is an example of how you can reply to that email. +Every email has a unique ID, which can be used to send a reply to that email. You can find the +Message-ID and the rest of the required information from Patchwork_, in the Headers section of +the patch that you want to reply to. + +The first step is to create the email, as a text file, which should look like this: + +.. image:: /_static/image5.png + +After you created the email, let’s refer to it as reply.txt, and you set up git send-email +(see `this guideline `_) +use the following command to send it: + +git send-email --to= **PATCH_SENDER** --cc=minios-devel@lists.xen.org reply.txt + + +######################### +Review guideline +######################### + +In this section, you can see good practices and common mistakes after which +you can look as a reviewer: + + * TBD + * TBD + * TBD \ No newline at end of file