Commit aa38251c authored by Dorota Czaplejewicz's avatar Dorota Czaplejewicz

contributing: Describe assignees and elaborate on MRs

This describes the conclusions about how to use the GitLab Assignee field in today's discussion. There MR sections were redacted to describe WIP MRs better as well as show that filing things gives benefits and responsibility. Workflow with multiple reviewers clarified slightly.
parent 5eabc034
Pipeline #146 passed with stage
in 40 seconds
......@@ -7,7 +7,14 @@ We welcome merge requests and issues being filed in our code repositories. Typic
Aside from project specific issues, we do have an `Apps_issues <https://source.puri.sm/Librem5/Apps_Issues>`_ project to track tasks like applications to port to the phone or issues with them. Here you can add a task for a particular app to be ported to the phone. However, be sure to search our `list of projects <https://source.puri.sm/Librem5/>`_ first before opening an issue under `Apps_issues <https://source.puri.sm/Librem5/Apps_Issues>`_.
If you wish to own an issue, you will need additional permissions in our GitLab so please reach out in the community/librem-5 Matrix room and ask for a team member to grant you the "Reporter" role for the relevant project.
Working on issues
*****************
Issues have an *Assignee* field, which is used for indicating that someone is working on it. Other people can avoid doing the same work if it's already being taken care of. Often, it will be the same person who filed the issue, but anyone interested can assign themselves.
If you are filing an issue, and you know someone else can solve it better than you can, please use the ``@mention`` to bring their attention. Don't assign other people yourself! Let them take a look before taking the responsibility.
If you wish to take up an issue yourself, you will need additional permissions in our GitLab so please reach out in the community/librem-5 Matrix room and ask for a team member to grant you the "Reporter" role for the relevant project.
Repository Guidelines
*********************
......@@ -34,27 +41,37 @@ The "production" repository will be in the https://source.puri.sm/Librem5/ space
Making Merge Requests
*********************
By making a merge request (MR) you are letting others know that your change has been tested and you feel it is ready to be live. Since MRs should be reviewed by another person and in order to minimize misspent effort, we have come up with a short set of guidelines around merge requests.
Merge requests (MRs) are meant for code which you would like to get merged. There are two possible types of those:
* *Work In Progress* requests have the "WIP: " prefix in the title and are meant to gather feedback on the idea. These MRs won't necessarily be tested, and will not be merged. The following guidelines don't apply to them. However, the author may remove the "WIP: " prefix, making it a regular merge request.
* Regular merge requests are a way for the author to take a commitment to work on the code. In exchange, the project maintainers will provide feedback and include the change when they think it's appropriate.
By making a merge request you are letting others know that your change has been tested and you feel it is ready to be live. Since MRs should be reviewed by another person and in order to minimize misspent effort, we have come up with a short set of guidelines around merge requests.
* In the merge request, add a sign off line signifying that you agree that your work is used under the license of the project being contributed to: ``Signed-off-by: Random J Developer <random@developer.example.org>``
* Anyone that is making a MR should have tested their change.
* Alert someone to review the MR.
* While you may require more than one reviewer (depends on the change), only one tester is required.
* Alert someone to review the MR, ideally by using a ``@mention``.
* If there is no single person that knows the affected areas well, alert multiple people.
.. note:: If you have a MR that depends on another outstanding MR (or if you only want feedback without a merge), prepend your MR title with "WIP". For more info on WIP, see `gitlab's WIP documentation <https://docs.gitlab.com/ee/user/project/merge_requests/work_in_progress_merge_requests.html>`_
Reviewing Merge Requests
************************
Follow these steps to succesfully review someone's MR:
*Work In Progress* merge requests serve only as a place for discussion, therefore no special procedure is required. For all other merge requests, please adhere to the following guidelines.
Merge requests come in different sizes, and depending on the complexity, one or more people may want to review it. However, it's enough that one person tests it.
* Build and test the change in question.
To succesfully review someone's MR, first indicate that you are reviewing the MR by making yourself the *Assignee*, or by saying that explicitly in the comments. Then:
* Build and test the newest version of the MR if no other reviewer did that yet.
* Provide feedback in the MR discussion. This is where you would mention additional changes needed.
* Once all changes are approved, the reviewer should acknowledge that they tested it in the MR discussion.
* Merge the request.
Once all reviewers are satisfied with the MR, merge it.
Do NOT merge the request if any of these are true:
* The MR has "WIP" in the title. These MRs do not have to pass tests and reviewers are meant to provide feedback only.
* If no one has built and tested the change
* The MR has "WIP" in the title.
* If no reviewer tested the current version of the MR.
* If there are unresolved discussions.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment