Gatekeeping: Guide for developer

Posted . Visible to the public.

Note: This has been a private card for some time, because it is heavily tailored to our specific needs and tools. While it will certainly not apply to all (especially larger teams), we thought it might still be helpful as a starting point, and so made it public. Compare also the Gatekeeping: Guide for gatekeeper card.


In order to reduce the number of rejects we get from clients, we want to review all code written before it goes to the staging server.

If your project manager wants to do gatekeeping on a project, as a developer you need to follow the following guidelines.

Role of the master branch

You're generally not allowed to commit anything directly to master, except if you're asked to, or if you're fixing a reject from our client.

Starting a new feature

If you start a new feature, you need to:

  • Pull the most current master branch
  • Branch off the master by doing
    git checkout master
    git checkout -b FEATURE_BRANCH_NAME

If your feature depends on another feature branch that is not yet in the master, branch off that branch instead.

Name your branch like feature/73624-sort-users-by-name, i.e. start with feature, then the PT story id, then a shortened story description.

Code and commit like usual. You may leave WIP commits, since they will be cleaned up later.

Finishing a feature

When you're done with your feature and tests are green, you need to:

  • Within your feature branch, merge the current master and push using:
    git pull origin master
    git push -u origin feature-branch-name

    You're encouraged to use git pull --rebase if you know how it works.

  • Open a merge request on GitLab by:

    • Opening the project
    • Clicking "Merge Request" in the box on the right
    • Filling in
      • "From" with your feature branch
      • "To" with "master"
      • "Assign to" with the project manager
      • "Title" with a descriptive name, preferably using the story id and title from PT. Use gitpt or the commit bookmarklet to auto-generate the title.
    • Copy and check the Merge request check list as a comment.
  • Set the story to "Finished" on PT

If your code passes review

Your project manager will either merge and deploy the changes, or he will ask you to do it yourself in a note to the merge request (you will receive an e-mail)

If you're supposed to merge yourself, you need to
^

  • Squash your commits using git rebase -i or something similar
  • Merge into master
    ^
    git checkout master
    git pull
    git merge feature-branch-name
    ^
  • Push
  • Delete the feature branch with
    ^
    git branch -d feature-branch-name
    git push origin :feature-branch-name
    ^
  • Deploy to staging
  • Set the corresponding PT story to “delivered”
  • Close the merge request on GitLab

If your code is rejected by the project manager

If your code does not pass review, your story will be rejected on PT, with an explanation either on PT or as a note in the merge request. You'll get an e-mail either way.

Fixes will be made within the existing feature branch. Prepare by doing a
git checkout FEATURE_BRANCH_NAME
git pull origin master

Now make your fixes. Again, squash WIP commits, but do not squash commits that have already been reviewed or merged into master. The gatekeeper needs to be able to see your changes separately.

When you're done, you may decide yourself (unless your project manager said otherwise),
^

  • if you want your changes to be reviewed again:
    • merge master and push again
    • your new commits will automatically turn up in the merge request
    • add a note to the merge request, indicating that the reject is fixed
  • or if you do not think another review is necessary:
    • merge, delete and deploy as above

If your code is rejected by the client

Since your branch has already been merged into master, you can make fixes directly in master and do not have to get them reviewed. If you want to get them reviewed, make a new feature branch for it.

Changes that do not need to be reviewed

As a good default, all non-trivial commits should be reviewed. However, your gatekeeper is allowed to make exceptions for changes where they don't think a review would add any value, e.g. for trivial changes (like fixing a typo). Another exception are client rejects, unless you want to get the fix reviewed.

If a change does not need to be reviewed, your project manager will add a note to the story that the code should be commited into the master branch without going through a merge request.

If two developers are working on the same code

In some cases it will be necessary to work on things in parallel. In this case, you are allowed to branch off someone else's (unfinished) feature branch, but please tell the person you're doing this.

You can keep working as usual, but the second developer to merge his branch needs to be a bit careful. You can still squash your commit as usual, but there is a chance that git will be unable to properly merge things. Please either

  • you try to merge, but review your final commit before pushing. Look out for changes that don't belong to your story (and are usually in place you never touched)
  • use git rebase --onto to rebase only your commit onto master
Christoph Beck
Posted by Christoph Beck to BitCrowd (2013-11-18 14:25)