Docs/MR process: precise the role of the Draft state
Context
The merge team has discussed the role of GitLab's draft status for MRs and it's interplay with the assignee
field of an MR.
The problem is the common uncertainty with regards to the questions:
- is this MR ready for review?
- is this MR ready to be merged?
And also, to handle the fact that Gitlab automatically marks MRs as Draft
when a fixup commit is pushed.
Proposal
In this MR, I updated the merge process to implement @naih proposal:
- Draft with a reviewer means ready to be reviewed but some cleaning-up to do; - Non-Draft with a reviewer means ready to be reviewed, and merged if approved?
This means that:
- An MR is ready for review when it is assigned to a reviewer -- regardless of the draft status
- An MR is ready to be merged when it is approved and is non-draft.
The reviewability of an MR is summarized by the following table:
Draft | Assignee | Reviewers | Reviewable |
---|---|---|---|
- | - | ∅ | |
Yes | Author | - | |
Yes | Others | Some | |
No | - | Some |
And consequently, the correct status of an MR is given by this table:
Assignee | Has fixups? | Correct status |
---|---|---|
Other | No | |
Other | Yes | Draft |
Author | No | Draft |
Author | Yes | Draft |
This change plays well with gitlabs automatically drafting MRs: pushing a fixup does not typically signal that the author no longer wishes their MR to be reviewed. Rather, it means they are in the review-process. Consequently, the Draft flag servers as a reminder that history should be rewritten once the MR is otherwise ready for merge.
Manually testing the MR
Checklist
-
Document the interface of any function added or modified (see the coding guidelines) -
Document any change to the user interface, including configuration parameters (see node configuration) -
Provide automatic testing (see the testing guide). -
For new features and bug fixes, add an item in the appropriate changelog ( docs/protocols/alpha.rst
for the protocol and the environment,CHANGES.rst
at the root of the repository for everything else). -
Select suitable reviewers using the Reviewers
field below. -
Select as Assignee
the next person who should take action on that MR