1(ch_submittingmr)= 2 3# Submitting a Merge Request 4 5`git push` prints a URL to the terminal that you can use to start a merge request. 6Alternatively, use [GitLab's web interface](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html). 7 8- The default **target** branch is `main`; if your branch started from `release`, select that as the target branch. 9- If the merge request resolves an outstanding [issue](https://gitlab.com/petsc/petsc/issues), 10 include a [closing pattern](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#default-closing-pattern) 11 such as `Closes #123` in the MR’s description to automatically have the issue closed when the MR is merged [^closing-patterns-release] . 12 13If you are not contributing from a fork: 14 15- Select appropriate [labels](https://gitlab.com/petsc/petsc/-/labels) including a {any}`workflow label <sec_workflow_labels>`. 16- Assign yourself to the MR. 17- Select reviewers for the MR; clicking on `> Approval Rules` will list appropriate reviewers. 18- If the branch started from `release` select the `milestone` of `Vxx.yy-release-fixes` 19- For changes only to documentation, add the `docs-only` label, which will 20 trigger a modified pipeline to build a preview of the documentation automatically. 21 Any warnings from Sphinx will cause the pipeline to fail. Once completed, click "View App" on the right side in the middle of the MR page. 22- If appropriate, once the MR has been submitted, refresh the browser and select Pipelines to examine and run testing; see doc:`/developers/contributing/pipelines`. 23 24For MRs from forks: 25 26- Make sure the fork is public -- as GitLab merge request process does not work well with a private fork. 27- Select the correct target repository `petsc/petsc` along with the target branch. 28- Select the "Allow commits from members who can merge to the target branch" option. 29- GitLab does not allow you to set labels, so `@`-mention one of the developers in a comment so they can assign someone to the MR to add labels, run pipelines, and generally assist with the MR. The assignee and submitter should be listed in the upper right corner as assignees to the MR. 30 31(sec_workflow_labels)= 32 33## Workflow labels 34 35The MR process, including testing and reviewing, is managed by [workflow labels](https://gitlab.com/petsc/petsc/-/labels?subscribed=&search=workflow%3A%3A) that indicate the state of the MR. Every MR should have exactly one of these labels. 36 37The standard workflow has three steps. 38 39- `workflow::Pipeline-Testing` The user is testing their branch. Generally, unless asked, no one else has a reason to look at such an MR. 40- `workflow::Review` The user would like their branch reviewed. 41- `workflow::Ready-For-Merge` The MR has passed all tests, passed the review, has no outstanding threads, and has a {any}`clean commit history <sec_clean_commit_history>`. 42 43The submitter/assignee of the MR is responsible for changing the `workflow` label appropriately during the MR process. 44 45Some MRs may begin with either of the following `workflow` states. 46 47- `workflow::Request-For-Comment` The branch is not being requested to be merged, but the user would like feedback on the branch. You do not need to test the code in this state. 48- `workflow::In-Development` The developer is working on the branch. Other developers not involved in the branch generally have no reason to look at these MRs. 49 50These should also be marked as "Draft" on the MR page. 51The developer usually eventually converts these two states to `workflow::Review`. 52 53You can run the pipelines on an MR in any workflow state. 54 55(sec_mr_reviewing)= 56 57## MR reviewing 58 59Once the MR has passed the pipeline, it is ready for review. 60The submitter/assignee must change the {any}`workflow label <sec_workflow_labels>` to `workflow::Review`. 61 62It is the **submitter/assignee’s** responsibility to track the progress of the MR 63and ensure it gets merged. 64 65If the pipeline detects problems, it is the **submitter/assignee’s** 66responsibility to fix the errors. 67 68Reviewers comment on the MR, either 69 70- by clicking on the left end of a specific line in the `Changes` window. A useful feature is the ["insert suggestion"](https://docs.gitlab.com/ee/user/project/merge_requests/reviews/suggestions.html) button in the comment box, to suggest an exact replacement on a line or several adjacent lines. 71- or in the overview if it is a general comment. When introducing a new topic (thread) in reviewing an MR, one should submit with "Start Review" and not "Comment". 72 73GitLab MRs use "threads" to track discussions. 74When responding to a thread, make sure to use the "Reply" box for that 75thread; do not introduce a new thread or a comment. 76 77The **submitter/assignee** must mark threads as resolved when they fix the related 78problem. 79 80Often, the submitter/assignee will need to update their branch in response to these comments, 81and re-run the pipeline. 82 83If the **submitter/assignee** feels the MR is not getting reviewed in a timely 84manner, they may assign additional reviewers to the MR and request in the MR discussion these same people to review by @-mentioning them. 85 86When reviewers believe an MR is ready to be merged, they approve it. 87You can determine who must approve your MR by clicking on the "View eligible reviewers" towards the top of the "Overview" page. 88 89When a sufficient number of reviewers has approved the merge, the pipeline passes, new commits have been {any}`properly rearranged <sec_clean_commit_history>` if needed, and all threads have been resolved, 90the **submitter/assignee** must set the label to {any}`workflow::Ready-For-Merge <sec_workflow_labels>`. 91 92```{rubric} Footnotes 93``` 94 95[^closing-patterns-release]: Unfortunately, these closing patterns [only work for MRs to a single default branch](https://gitlab.com/gitlab-org/gitlab/-/issues/14289) (`main`), so you must manually close related issues for MRs to `release`. 96