wiki:WorkingConventions/GitLabSPJ

GitLab's model

Here's a summary of the things in GitLab's universe, what they mean, and how they relate to each other.

  • Projects. Example: the GHC project. 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.
  • 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.
  • 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

You never commit directly to HEAD. Rather, follow this workflow.

  • Create a branch, e.g. wip/spj-wibbles or wip/T16224:
    $ git checkout -b wip/spj-wibbles
    
  • Push it to the main repo (or your private repo)
    $ git push -u origin wip/spj-wibbles
    
    The -u flag arranges that your private branch will now track the remote branch.
  • As you review it, you can add further patches to the branch, and push them. The MR as seen in GitLab is always the tip of the branch.
  • You can also rebase the patch on HEAD; then you need to force-push the branch
    $ 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.
  • 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.

In particular, do not click the "Merge if passes tests" button. That bypasses Marge and confuses her.

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.
  • 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.
  • Work in progress Merge Requests. A MR can be a "work in progress" (WIP) MR.
    • 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
  • 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:
    • A small per-project list of super-developers.
    • The code owners file: 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?

Per MR approvers: chosen from developer.

Gitlab tips

  • 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.
  • Notifications. For projects you care about (e.g. 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?
    • Go to the GHC project page
    • 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

      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.

Actually, git reports this when you push the branch too, if you remember to look. E.g.

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 a MR

  • Click on the Changes tab in the MR
  • I recommend clicking on "Side-by-side" to get a better rendering.
  • You also may want to go to your preferences page (accessible via the Settings button that appears under your picture at the very top-right of the screen -- Preferences is fourth from the bottom in the vertical navbar to the left of your settings screen) and choose a Fluid layout width.
  • Back on the "Changes" tab of the MR above, you'll see a button labeled "0/49 discussions resolved". There is a small button with an arrow in it to the right of that. It warps you to the first unresolved discussion (i.e. comment I've made during my review)
  • Comment if you like. Then, at the bottom-right of the windowette that contains the discussion, you'll see another button with a right-pointing arrow inside a speech bubble. Click that to go to the next unresolved discussion. In this way, the unresolved discussions can be navigated like a singly linked list.
  • 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.

Transitioning an old repo

$ git remote set-url origin https://gitlab.haskell.org/ghc/ghc.git
$ git remote set-url --push origin git@gitlab.haskell.org:ghc/ghc
$ git submodule sync
Last modified 6 months ago Last modified on Feb 26, 2019 4:20:41 PM