Updated: Gatekeeping: Guide for developer

Posted . Visible to the public. Auto-destruct in 26 days

Update our Gatekeeping workflow to refer to our new default workflow states in Linear

Changes

  • **Note**: This process is tailored to our specific needs and tools at [makandra](https://makandra.com). While it will certainly not apply to all (especially larger teams), we think it is a helpful starting point. Compare also the [Gatekeeping: Guide for gatekeeper](https://makandracards.com/makandra/6577-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 (e.g. by using something like this [story checklist template](https://makandracards.com/makandra/537519-story-checklist-template)).
  • +If your project manager wants to do gatekeeping on a project, as a developer you need to follow the following guidelines (e.g. by using something like this [issue checklist template](https://makandracards.com/makandra/537519)).
  • -Role of the master branch
  • +Role of the main/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.
  • +You're generally not allowed to commit anything directly to main, 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:
  • -- Set the story to "Started" in Pivotal Tracker
  • -- Pull the most current master branch
  • -- **Branch off the master** with `geordi branch` or manually with:
  • +- Set the issue to "Started: In Progress" in Linear
  • +- Pull the most current main branch
  • +- **Branch off the main** with `geordi branch` or manually with:
  • - git checkout master
  • + git checkout main
  • 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.
  • +If your feature depends on another feature branch that is not yet in the main, branch off that branch instead.
  • -**Name your branch** like `sort-users-by-name-73624`, i.e. start with a shortened story description, then the PT story id . You can also start your branch with your initials, so that everyone can see who is working on the branch, e.g. `ab/sort-users-by-name-73624`.
  • +**Name your branch** like `sort-users-by-name-73624`, i.e. start with a shortened issue description, then the Linear issue ID . You can also start your branch with your initials, so that everyone can see who is working on the branch, e.g. `ab/sort-users-by-name-73624`.
  • Code and commit like usual. You may leave WIP commits, since they will be cleaned up later. You may follow [this workflow](/makandra/36003-recommended-git-workflow-for-feature-branches).
  • Finishing a feature
  • -------------------
  • When you're done with your feature and tests are green, and your changes pass [our merge request checklist](/makandra/16515-merge-request-check-list):
  • -- Within your feature branch, **merge the current master and push** using:
  • +- Within your feature branch, **merge the current main and push** using:
  • - git pull origin master
  • + git pull origin main
  • 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** by clicking the link Gitlab prints on push.
  • - To open a merge request manually:
  • - Open the project
  • - Click "Merge Request" in the box on the right
  • - Fill in
  • - "From" with your feature branch
  • - - "To" with "master"
  • + - "To" with "main"
  • - "Assign to" with yourself
  • - "Reviewer" with your project manager
  • - - "Title" with a descriptive name, preferably using the story id and title from PT. Use [gitpt](https://makandracards.com/makandra/1372-shell-script-to-generate-a-git-commit-with-pivotal-tracker-story-id-and-title) or the [commit bookmarklet](https://makandracards.com/makandra/851-bookmarklet-to-generate-a-commit-message-with-pivotal-tracker-story-id-and-title) to auto-generate the title.
  • - - "Description", add a link to your pivotal tracker story and Screenshots of any UI Changes
  • + - "Title" with a descriptive name, preferably using the issue id and title from Linear. Use the [commit bookmarklet](https://makandracards.com/makandra/620718-bookmarklet-to-generate-a-commit-message-for-an-issue-in-linear-app) to auto-generate the title.
  • + - "Description", add a link to your Linear issue and Screenshots of any UI Changes
  • -- Set the story to "Finished" in the Pivotal Tracker
  • +- Set the issue to "Review" in Linear
  • 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
  • -- **Get the latest master**
  • -- **Squash your commits** using [`git rebase -i master`](527-squash-several-git-commits-into-a-single-commit) or something similar
  • - - [Make sure the commit message matches our guideline](https://makandracards.com/makandra/851-bookmarklet-to-generate-a-commit-message-with-pivotal-tracker-story-id-and-title)
  • -- **Merge into master**
  • +- **Get the latest main**
  • +- **Squash your commits** using [`git rebase -i main`](527-squash-several-git-commits-into-a-single-commit) or something similar
  • + - [Make sure the commit message matches our guideline](https://makandracards.com/makandra/620718-bookmarklet-to-generate-a-commit-message-for-an-issue-in-linear-app)
  • +- **Merge into main**
  • - git checkout master
  • + git checkout main
  • git merge feature-branch-name
  • - **Push**
  • - Delete the feature branch with
  • git branch -D feature-branch-name
  • git push origin :feature-branch-name
  • - You might want to consider using [this hook](https://makandracards.com/makandra/515762-git-removing-feature-branches-on-merge) instead.
  • - **Deploy** to staging
  • -- Set the corresponding **PT story to “delivered”**
  • +- Set the corresponding **Linear issue to “On Staging”**
  • - **Close the merge request** on GitLab (happens automatically when you merge or delete the remote branch)
  • 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.
  • +If your code does not pass review, your issue will be rejected on Linear, with an explanation either on Linear or as a note in the merge request. You'll get an e-mail either way.
  • -- Set the story to "Started" in Pivotal Tracker and track it's state as usual
  • +- Set the issue to "In Progress" in Linear and track it's state as usual
  • - Fixes will be made **within the existing feature branch**.
  • Prepare by doing a
  • git checkout FEATURE_BRANCH_NAME
  • - git pull origin master
  • + git pull origin main
  • -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.
  • +Now **make your fixes**. Again, squash WIP commits, but do not squash commits that have already been reviewed or merged into main. 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
  • + - merge main 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.
  • +Since your branch has already been merged into main, you can make fixes directly in main and do not have to get them reviewed. If you **want** to get them reviewed, make a **new feature branch** for it.
  • -Set the story to "Started" in Pivotal Tracker and track it's state as usual.
  • +Set the issue to "In Progress" in Linear and track it's state as usual.
  • 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 a change does not need to be reviewed, your project manager will add a note to the issue that the code should be commited into the main 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)
  • - + when you open a merge request make sure that you show the diffs to the branch you branched off from, so select to merge into this branch on merge request in gitlab. When you actually merge don't forget to **merge into master** instead!
  • -- use [`git rebase --onto`](10173-git-how-to-rebase-your-feature-branch-from-one-branch-to-another) to rebase only your commit onto master
  • +- you try to merge, but review your final commit before pushing. Look out for changes that don't belong to your issue (and are usually in place you never touched)
  • + + when you open a merge request make sure that you show the diffs to the branch you branched off from, so select to merge into this branch on merge request in gitlab. When you actually merge don't forget to **merge into main** instead!
  • +- use [`git rebase --onto`](10173-git-how-to-rebase-your-feature-branch-from-one-branch-to-another) to rebase only your commit onto main
  • * Also check [Git: rebase dependent feature branch after squash](https://makandracards.com/makandra/45964-git-rebase-dependent-feature-branch-after-squash)
Michael Leimstädtner
License
Source code in this card is licensed under the MIT License.
Posted by Michael Leimstädtner to makandra dev (2024-06-13 14:11)