|
|
# GitLab's model
|
|
|
# The big picture
|
|
|
|
|
|
|
|
|
Here's a summary of the things in GitLab's universe, what they mean, and how they relate to each other.
|
|
|
- A **merge request** (MR) a set of changes that you want to have merged into HEAD.
|
|
|
|
|
|
- **Groups.** Example, the [ GHC group](https://gitlab.haskell.org/ghc)
|
|
|
|
|
|
- A group contains:
|
|
|
- Every MR has an associated **GIT branch**. It is this branch that will be ultimately merged into HEAD.
|
|
|
|
|
|
- *Members*, each of whom is a *user*.
|
|
|
- *Projects*
|
|
|
- *Sub-groups*
|
|
|
- As "sub-groups" suggests, groups can nest. For example [ GHC packages group](https://gitlab.haskell.org/ghc/packages) is a sub-group of the [ GHC group](https://gitlab.haskell.org/ghc)
|
|
|
|
|
|
- **Projects.** Example: the [ GHC project](https://gitlab.haskell.org/ghc/ghc). A *project* has
|
|
|
|
|
|
- A *git repository*
|
|
|
- A *wiki*
|
|
|
- An *issue tracker*
|
|
|
- An *owner*, who is either a group or a user. **Question**: exactly one owner?
|
|
|
A project can accept merge requests.
|
|
|
|
|
|
- **Users.**
|
|
|
|
|
|
- A user can be a *member* of (a) groups and (b) projects.
|
|
|
- There are a few flavours of membership, called "roles". These include "reporter", "developer", "maintainer", and "owner"; which all imply different sets of permissions, [ documented here](https://docs.gitlab.com/ee/user/permissions.html).
|
|
|
|
|
|
- A **merge request** (MR) is a set of one or more commits that you want to have merged into master.
|
|
|
|
|
|
- Every MR has an associated **GIT branch**. It is this branch that will be ultimately merged into master.
|
|
|
- The branch may have multiple commits; these are all merged individually onto master.
|
|
|
- An **issue** is GitLab's name for a Trac ticket.
|
|
|
|
|
|
- A **review** is a set of comments on a MR. Always comment on MRs using a review, else the recipients get one email per comment, which is terrible.
|
|
|
|
|
|
- An **issue** is GitLab's name for a Trac ticket.
|
|
|
|
|
|
# Workflows
|
|
|
|
|
|
## Making a change to the master repository
|
|
|
|
|
|
## Making a change to HEAD
|
|
|
|
|
|
|
|
|
|
|
|
You never commit directly to HEAD. Rather, follow this workflow.
|
... | ... | @@ -50,11 +27,9 @@ You never commit directly to HEAD. Rather, follow this workflow. |
|
|
- Push it to the main repo (or your private repo)
|
|
|
|
|
|
```wiki
|
|
|
$ git push -u origin wip/spj-wibbles
|
|
|
$ git push origin wip/spj-wibbles
|
|
|
```
|
|
|
|
|
|
The `-u` flag arranges that your private branch will now track the remote branch.
|
|
|
|
|
|
- Create a merge request. [ More details on this process are here](https://gitlab.haskell.org/ghc/ghc/wikis/home#opening-a-merge-request).
|
|
|
|
|
|
- Working with your merge request: [ details here](https://gitlab.haskell.org/ghc/ghc/wikis/home#working-with-your-merge-request).
|
... | ... | @@ -67,77 +42,67 @@ You never commit directly to HEAD. Rather, follow this workflow. |
|
|
$ git push --force origin wip/spj-wibbles
|
|
|
```
|
|
|
|
|
|
- Before trying to commit to master, you should tidy up the MR by squashing it into one (or more in unusual cases) patch, with a good commit message.
|
|
|
- Before trying to commit to HEAD, you should tidy up the MR by squashing it into one (or more in unusual cases) patch, with a good commit message.
|
|
|
|
|
|
- When you are ready to commit to master, you do this by **assigning to Marge**. Go to "Edit" the MR, and set the "Assignee" to "Marge". That's all you have to do. Marge will rebase you patch on master, validate, and commit.
|
|
|
- Someone with commit right can then click "merge" on that MR. Even then it has to pass CI before it lands in HEAD.
|
|
|
|
|
|
>
|
|
|
> In particular, **do not click the "Merge if passes tests" button**. That bypasses Marge and confuses her.
|
|
|
# GitLab model
|
|
|
|
|
|
# GitLab notes
|
|
|
|
|
|
## Merge requests
|
|
|
|
|
|
- **The title and description of a MR** do not form part of the Git repo's history. Only the commit messages in the patches do. So make sure that each patch has a good commit message! The title and description of the MR signpost the readers through the review process.
|
|
|
This section summarises what I understand about GitLab's semantics: what things there are and how they relate to each other.
|
|
|
|
|
|
- To see all merge requests, click on "Merge requests" *in the left-hand nav column*. The similar icon in the black menu bar at the top doesn't seem to do anything useful.
|
|
|
|
|
|
- To see more code surrounding a diff, there are some light grey "..." icons at the top and bottom of the line-number column. Click to show more.
|
|
|
- **Groups.** Example, the [ GHC group](https://gitlab.haskell.org/ghc)
|
|
|
|
|
|
- **Work in progress Merge Requests**. A MR can be a "work in progress" (WIP) MR.
|
|
|
- A group contains:
|
|
|
|
|
|
- WIP MRs are identified simply by having a title beginning "WIP:" or "\[WIP\]".
|
|
|
- The "merge" button is disabled for WIP MRs, so they can't be accidentally merged.
|
|
|
Details [ here](https://docs.gitlab.com/ee/user/project/merge_requests/work_in_progress_merge_requests.html)
|
|
|
- *Members*, each of whom is a *user*.
|
|
|
- *Projects*
|
|
|
- *Sub-groups*
|
|
|
- As "sub-groups" suggests, groups can nest. For example [ GHC packages group](https://gitlab.haskell.org/ghc/packages) is a sub-group of the [ GHC group](https://gitlab.haskell.org/ghc)
|
|
|
|
|
|
- **Projects.** Example: the [ GHC project](https://gitlab.haskell.org/ghc/ghc). A *project* has
|
|
|
|
|
|
- A *git repository*
|
|
|
- A *wiki*
|
|
|
- An *issue tracker*
|
|
|
- An *owner*, who is either a group or a user. **Question**: exactly one owner?
|
|
|
A project can accept merge requests.
|
|
|
|
|
|
- **Approvers**. A MR requires at least one approver to press the "Approve" button before a MR will be merged. The approvers for a MR are drawn from three sources:
|
|
|
- **Users.**
|
|
|
|
|
|
- A small per-project list of super-developers.
|
|
|
- The [ code owners file](https://gitlab.haskell.org/ghc/ghc/blob/master/CODEOWNERS): if your patch touches code listed in this file, the corresponding users become approvers for that MR.
|
|
|
- Per-MR approvers, which you as MR author can add. *From what list?*****
|
|
|
- A user can be a *member* of (a) groups and (b) projects.
|
|
|
- There are a few flavours of membership ("reporter", "developer", "maintainer", and "owner") which all imply different sets of permissions, [ documented here](https://docs.gitlab.com/ee/user/permissions.html).
|
|
|
|
|
|
# GitLab notes
|
|
|
|
|
|
Per MR approvers: chosen from developer.
|
|
|
|
|
|
## Gitlab tips
|
|
|
|
|
|
- **Markup**. In GitLab markup:
|
|
|
|
|
|
- In GitLab markup:
|
|
|
|
|
|
- `#3553` links to issue 3553
|
|
|
- `!883` links to merge request 883
|
|
|
|
|
|
- **Zooming**. If you zoom your browser too much, stuff starts disappearing from the top menu bar; e.g. your picture and the settings linked to it. You have to zoom out.
|
|
|
- If you zoom your browser too much, stuff starts disappearing from the top menu bar; e.g. your picture and the settings linked to it. You have to zoom out.
|
|
|
|
|
|
- **Notifications**. For projects you care about (e.g. [ https://gitlab.haskell.org/ghc/ghc](https://gitlab.haskell.org/ghc/ghc)), click on "Watch" (there's a little bell icon) about four rows down from the top. Then you'll get notifications of what changes.
|
|
|
- For projects you care about (e.g. [ https://gitlab.haskell.org/ghc/ghc](https://gitlab.haskell.org/ghc/ghc)), click on "Watch" (there's a little bell icon) about four rows down from the top. Then you'll get notifications of what changes.
|
|
|
|
|
|
- **From branch name to merge request**. Say you are on branch `wip/T16185`, and you know you (or someone) has submitted a MR based on that branch. How can you find the MR?
|
|
|
## Merge requests
|
|
|
|
|
|
|
|
|
- The title and description of a MR do not form part of the Git repo's history. Only the commit messages in the patches do. So make sure that each patch has a good commit message! The title and description of the MR signpost the readers through the review process.
|
|
|
|
|
|
- When commenting on a MR, use "Start review", not "Add comment". The latter sends an email for each comment. But a "review" is a set of comments, and the recipients get one email for the whole thing.
|
|
|
|
|
|
- Go to the [ GHC project page](https://gitlab.haskell.org/ghc/ghc)
|
|
|
- Select the branch (drop-down menu box near the top left; initially labelled *master*).
|
|
|
- In the left-hand-column menu bar, from "Repository" select "Commits"
|
|
|
- Click on the title of the top-most commit
|
|
|
- To see all merge requests, click on "Merge requests" *in the left-hand nav column*. The similar icon in the black menu bar at the top doesn't seem to do anything useful.
|
|
|
|
|
|
You should then see something like "1 merge request!128 WIP: Add an AnonArgFlag to FunTy" near the top, if there is an active MR from this branch.
|
|
|
- To see more code surrounding a diff, there are some light grey "..." icons at the top and bottom of the line-number column. Click to show more.
|
|
|
|
|
|
>
|
|
|
> Actually, git reports this when you push the branch too, if you remember to look. E.g.
|
|
|
>
|
|
|
> ```wiki
|
|
|
> bash$ git push --force
|
|
|
> Counting objects: 80, done.
|
|
|
> Delta compression using up to 32 threads.
|
|
|
> Compressing objects: 100% (80/80), done.
|
|
|
> Writing objects: 100% (80/80), 25.29 KiB | 0 bytes/s, done.
|
|
|
> Total 80 (delta 75), reused 0 (delta 0)
|
|
|
> remote:
|
|
|
> remote: View merge request for wip/T15952-2: <-- Here --------
|
|
|
> remote: https://gitlab.haskell.org/ghc/ghc/merge_requests/206
|
|
|
> remote:
|
|
|
> To git@gitlab.haskell.org:ghc/ghc
|
|
|
> + 5f84b0c...5c1f268 HEAD -> wip/T15952-2 (forced update)
|
|
|
> ```
|
|
|
## Reviewing comments
|
|
|
|
|
|
## Reviewing a MR
|
|
|
|
|
|
- Click on the Changes tab in the MR
|
|
|
|
... | ... | @@ -151,22 +116,9 @@ Per MR approvers: chosen from developer. |
|
|
|
|
|
- The table-of-contents on the left is useful, but it takes up a lot of visual space. To hide it, press the button with the three horizontal lines to the left of the words "Changes between", right below the tabs where you choose between, e.g., Discussion and Changes.
|
|
|
|
|
|
- When commenting on a MR, use "Start review", not "Add comment". The latter sends an email for each comment. But a "review" is a set of comments, and the recipients get one email for the whole thing.
|
|
|
|
|
|
## GitLab "quick actions"
|
|
|
|
|
|
|
|
|
Quick actions are textual shortcuts for common actions on issues, epics, merge requests, and commits that are usually done by clicking buttons or dropdowns in GitLab's UI.
|
|
|
|
|
|
- You can enter these commands while creating a new issue or merge request, or in comments of issues, epics, merge requests, and commits.
|
|
|
- Each command should be on a separate line in order to be properly detected and executed.
|
|
|
- Once executed, the commands are removed from the text body and not visible to anyone else.
|
|
|
|
|
|
|
|
|
There's a [ full list here](https://docs.gitlab.com/ee/user/project/quick_actions.html).
|
|
|
|
|
|
## Transitioning an old repo
|
|
|
|
|
|
|
|
|
```wiki
|
|
|
$ git remote set-url origin https://gitlab.haskell.org/ghc/ghc.git
|
|
|
$ git remote set-url --push origin git@gitlab.haskell.org:ghc/ghc
|
... | ... | |