... | ... | @@ -32,58 +32,18 @@ Submitting a patch for incorporation into the tree is done by creating a *merge |
|
|
|
|
|
If you are blocked waiting at any stage then please apply the ~"Blocked on Review" label and leave a comment mentioning @triagers to draw attention to the MR.
|
|
|
|
|
|
## 2. Opening a merge request
|
|
|
|
|
|
To open a merge request:
|
|
|
|
|
|
1. Push your branch. You may push either to your fork or the primary ghc/ghc> project.
|
|
|
2. Starting from the [GHC GitLab project](https://gitlab.haskell.org/ghc/ghc) click on the *Merge Requests* link in the left navigational bar.
|
|
|
3. Click on the green *New Merge Request* button on the top right corner of the Merge Requests page
|
|
|
4. In the left drop-down of the *Source branch* pane select the project to which you pushed your branch.
|
|
|
5. In the right drop-down of the *Source branch* pane select the name of your branch.
|
|
|
6. Click on the green *Compare branches and continue* button.
|
|
|
7. Give your merge request a title. Suffix with the issue number e.g "Fix some bug #12345"
|
|
|
8. Write a description of your change. This should be ideally at very least a few sentences to help reviewers understand what you have done. If your change requires any changes to [submodules](https://gitlab.haskell.org/ghc/ghc/-/wikis/working-conventions/git/submodules), please be sure to include links to the upstream merge requests in your description.
|
|
|
9. Click on the green *Submit merge request* button.
|
|
|
|
|
|
## 3. Working with your merge request
|
|
|
|
|
|
Your merge request shows you several panes of information:
|
|
|
|
|
|
Top-most is the request's title and description. These can be edited by pressing the yellow `Edit` button on the top-right corner of the page.
|
|
|
|
|
|
The next pane summarises your merge request, showing the source and target branches.
|
|
|
|
|
|
![request-summary](uploads/a6b259498530ea48964a11c2539447d2/request-summary.png)
|
|
|
|
|
|
The next pane shows the status of the merge request's continuous integration builds. If the build has failed you can click on the red *X* icon to see the build log.
|
|
|
|
|
|
![pipeline](uploads/3e1bf21a870eef5608665f9d6e6a48de/pipeline.png)
|
|
|
|
|
|
At the bottom of the page is the code review interface, consisting of several tabs:
|
|
|
|
|
|
![code-review](uploads/f90d8a2f0a3716669546ae1fd43480c1/code-review.png)
|
|
|
|
|
|
The *Discussion* tab shows a summary of the comments left on the change. This includes comments left in-line in the code, as well as those independent of the code.
|
|
|
|
|
|
The *Commits* tab lists the commits being proposed for merge. These may be clicked upon to restrict the diff to only changes made by that commit.
|
|
|
|
|
|
The *Pipelines* tab provides a more detailed overview on the state of the various continuous integration jobs associated with the merge request.
|
|
|
|
|
|
Finally, the *Changes* tab shows the patch itself. This view may be restricted to changes made by a single commit by selecting the commit in the *Commits* tab. Moreover, one may view previous iterations of the merge request using the two drop-down menus at the top of the tab. To leave an inline comment click on a line in the patch.
|
|
|
|
|
|
|
|
|
## 4. Draft Status
|
|
|
## 2. Draft Status
|
|
|
|
|
|
You can mark a MR as "draft" or "work in progress" by beginning the title with the string `Draft:` or `WIP:`. (The two are equivalent.)
|
|
|
|
|
|
### 4.1 What does it mean for an MR to be marked as Draft?
|
|
|
### 2.1 What does it mean for an MR to be marked as Draft?
|
|
|
|
|
|
* It signals that your MR is not ready for review; you are working on it. (Of course, you are free to ask someone for a review.)
|
|
|
* The automated merge system (marge-bot) will not merge a Draft MR into master.
|
|
|
* Maintainers are unlikely to fix CI issues, review or rebase such patches.
|
|
|
|
|
|
### 4.2 Why has someone changed my MR marked as Draft?
|
|
|
### 2.2 Why has someone changed my MR marked as Draft?
|
|
|
|
|
|
There are a number of reasons why an MR might be marked as draft by someone else:
|
|
|
|
... | ... | @@ -92,7 +52,7 @@ There are a number of reasons why an MR might be marked as draft by someone else |
|
|
* The patch needs outside input to proceed (ghc-proposal approval, clc-proposal approval, upstream changes, community feedback)
|
|
|
* The patch is still being worked on.
|
|
|
|
|
|
### 4.3 When should I remove "Draft" from my MR?
|
|
|
### 2.3 When should I remove "Draft" from my MR?
|
|
|
|
|
|
* If you want review or help on design and implementation aspects of your MR.
|
|
|
* If you think there are no remaining issues with your MR and it's ready to be merged into master.
|
... | ... | @@ -102,7 +62,7 @@ If you are in doubt it's **always ok to remove "Draft"**. A MR not marked ready |
|
|
|
|
|
Worst case a maintainer will mark it as Draft again if they think it's up to you to make changes to the MR before moving forward.
|
|
|
|
|
|
## 5. Review checklist
|
|
|
## 3. Review checklist
|
|
|
|
|
|
See the [merge request description template](https://gitlab.haskell.org/ghc/ghc/-/blob/master/.gitlab/merge_request_templates/Default.md) for a checklist of requirements for a merge request.
|
|
|
|
... | ... | @@ -125,7 +85,7 @@ When reviewing a merge request here are a few things to check for: |
|
|
|
|
|
To ensure that all interested reviewers have an opportunity to comment, please leave at least 24 hours between the time an MR is opened and assigning to @marge-bot.
|
|
|
|
|
|
## 6. Modifying the validation pipeline
|
|
|
## 4. Modifying the validation pipeline
|
|
|
|
|
|
By default we run a selected few jobs in each merge request on the most common platforms.
|
|
|
|
... | ... | @@ -141,7 +101,7 @@ You can use *labels* to modify the configurations which are tested on a merge re |
|
|
|
|
|
You apply a label using the "Labels" button in the right hand column.
|
|
|
|
|
|
## 7. Merging your merge request
|
|
|
## 5. Merging your merge request
|
|
|
|
|
|
We use @marge-bot to automatically rebase and merge branches to `master`.
|
|
|
After your merge request has been reviewed and approved, you can request that it be added to the merge queue by @-mentioning @triagers. Your MR should be added to the merge queue within a day or two, assuming it passes CI and the commit history is in order (individually buildable commits with informative commit messages).
|
... | ... | @@ -154,11 +114,11 @@ As long as your MR satisfies the following, GitLab will batch your MR with other |
|
|
|
|
|
Each batch is an MR of its own, which must itself pass CI. You can expect GitLab to merge two or three batches per day.
|
|
|
|
|
|
## 8. Rebasing
|
|
|
## 6. Rebasing
|
|
|
|
|
|
You generally do *not* need to rebase your MRs unless there are merge conflicts with `master`. GitLab will automatically rebase on top of `master` when batching MRs.
|
|
|
|
|
|
## 9. Backports
|
|
|
## 7. Backports
|
|
|
|
|
|
After a patch has made it to `master` it might be appropriate to backport it to the stable branch (e.g. `ghc-8.8`). If backporting is desired first ensure that the issue is milestoned for the next minor release and mark the merge request containing the fix with the appropriate "backport needed" label(s) (e.g. ~"backport needed:9.8").
|
|
|
|
... | ... | @@ -170,3 +130,48 @@ While the release manager can perform the backport on your behalf, it is appreci |
|
|
After the merge request is created ensure it has the ~backport label applied and that its milestone is set appropriately.
|
|
|
|
|
|
Once the backport MR lands the ~"backport needed" label can be removed from the source MR.
|
|
|
|
|
|
## 8. GitLab mechanics
|
|
|
|
|
|
Here we give a bit more guidance about the mechanics of merge requests
|
|
|
|
|
|
### 8.1. Opening a merge request
|
|
|
|
|
|
To open a merge request:
|
|
|
|
|
|
1. Push your branch. You may push either to your fork or the primary ghc/ghc> project.
|
|
|
2. Starting from the [GHC GitLab project](https://gitlab.haskell.org/ghc/ghc) click on the *Merge Requests* link in the left navigational bar.
|
|
|
3. Click on the green *New Merge Request* button on the top right corner of the Merge Requests page
|
|
|
4. In the left drop-down of the *Source branch* pane select the project to which you pushed your branch.
|
|
|
5. In the right drop-down of the *Source branch* pane select the name of your branch.
|
|
|
6. Click on the green *Compare branches and continue* button.
|
|
|
7. Give your merge request a title. Suffix with the issue number e.g "Fix some bug #12345"
|
|
|
8. Write a description of your change. This should be ideally at very least a few sentences to help reviewers understand what you have done. If your change requires any changes to [submodules](https://gitlab.haskell.org/ghc/ghc/-/wikis/working-conventions/git/submodules), please be sure to include links to the upstream merge requests in your description.
|
|
|
9. Click on the green *Submit merge request* button.
|
|
|
|
|
|
## 8.2. Working with your merge request
|
|
|
|
|
|
Your merge request shows you several panes of information:
|
|
|
|
|
|
Top-most is the request's title and description. These can be edited by pressing the yellow `Edit` button on the top-right corner of the page.
|
|
|
|
|
|
The next pane summarises your merge request, showing the source and target branches.
|
|
|
|
|
|
![request-summary](uploads/a6b259498530ea48964a11c2539447d2/request-summary.png)
|
|
|
|
|
|
The next pane shows the status of the merge request's continuous integration builds. If the build has failed you can click on the red *X* icon to see the build log.
|
|
|
|
|
|
![pipeline](uploads/3e1bf21a870eef5608665f9d6e6a48de/pipeline.png)
|
|
|
|
|
|
At the bottom of the page is the code review interface, consisting of several tabs:
|
|
|
|
|
|
![code-review](uploads/f90d8a2f0a3716669546ae1fd43480c1/code-review.png)
|
|
|
|
|
|
The *Discussion* tab shows a summary of the comments left on the change. This includes comments left in-line in the code, as well as those independent of the code.
|
|
|
|
|
|
The *Commits* tab lists the commits being proposed for merge. These may be clicked upon to restrict the diff to only changes made by that commit.
|
|
|
|
|
|
The *Pipelines* tab provides a more detailed overview on the state of the various continuous integration jobs associated with the merge request.
|
|
|
|
|
|
Finally, the *Changes* tab shows the patch itself. This view may be restricted to changes made by a single commit by selecting the commit in the *Commits* tab. Moreover, one may view previous iterations of the merge request using the two drop-down menus at the top of the tab. To leave an inline comment click on a line in the patch.
|
|
|
|