... | ... | @@ -32,18 +32,35 @@ 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. Tickets, merge requests, and commits
|
|
|
|
|
|
## 2. Draft Status
|
|
|
### 2.1 Every MR should have a ticket
|
|
|
|
|
|
* A *ticket* or *issue* (e.g. #21623) describes a *problem*.
|
|
|
* A *merge request* (e.g. !8750) describes a *solution*.
|
|
|
|
|
|
Every MR should point to the tickets that it solves. If you find yourself writing an MR without a ticket, consider opening a ticket that describes the problem you are solving.
|
|
|
|
|
|
### 2.2 Commit messages
|
|
|
|
|
|
Commit messages should aim to describe the changes a patch makes, e.g. "This patch modifies the Core simplifier to implement a new form of inlining pragma". Include ample information, in particular which commit the ticket fixed (if applicable) and which parts of the compiler are affected. This information is important to help GHC maintainers bisect regressions, compare features across branches, prepare release notes, etc.
|
|
|
|
|
|
The main content of a commit message should *not* be an explanation of the current implementation. This information is harder to find in a commit message, and (much worse) there is no explicit indication in the code that there is carefully-written information available about that particular line of code. Prefer instead writing an explanatory Note in the code, which you refer to in the commit message.
|
|
|
|
|
|
In short, commit messages describe *changes*, whereas comments explain the code *as it now is*.
|
|
|
|
|
|
|
|
|
## 3. 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.)
|
|
|
|
|
|
### 2.1 What does it mean for an MR to be marked as Draft?
|
|
|
### 3.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.
|
|
|
|
|
|
### 2.2 Why has someone changed my MR marked as Draft?
|
|
|
### 3.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:
|
|
|
|
... | ... | @@ -52,7 +69,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.
|
|
|
|
|
|
### 2.3 When should I remove "Draft" from my MR?
|
|
|
### 3.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.
|
... | ... | @@ -62,7 +79,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.
|
|
|
|
|
|
## 3. Review checklist
|
|
|
## 4. 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.
|
|
|
|
... | ... | @@ -85,7 +102,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.
|
|
|
|
|
|
## 4. Modifying the validation pipeline
|
|
|
## 5. Modifying the validation pipeline
|
|
|
|
|
|
By default we run a selected few jobs in each merge request on the most common platforms.
|
|
|
|
... | ... | @@ -101,7 +118,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.
|
|
|
|
|
|
## 5. Merging your merge request
|
|
|
## 6. 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).
|
... | ... | @@ -114,11 +131,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.
|
|
|
|
|
|
## 6. Rebasing
|
|
|
## 7. 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.
|
|
|
|
|
|
## 7. Backports
|
|
|
## 8. 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").
|
|
|
|
... | ... | @@ -131,11 +148,11 @@ After the merge request is created ensure it has the ~backport label applied and |
|
|
|
|
|
Once the backport MR lands the ~"backport needed" label can be removed from the source MR.
|
|
|
|
|
|
## 8. GitLab mechanics
|
|
|
## 9. GitLab mechanics
|
|
|
|
|
|
Here we give a bit more guidance about the mechanics of merge requests
|
|
|
|
|
|
### 8.1. Opening a merge request
|
|
|
### 9.1. Opening a merge request
|
|
|
|
|
|
To open a merge request:
|
|
|
|
... | ... | @@ -149,7 +166,7 @@ To open a merge request: |
|
|
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
|
|
|
## 9.2. Working with your merge request
|
|
|
|
|
|
Your merge request shows you several panes of information:
|
|
|
|
... | ... | |