Git Workflow KungFu

In terms of productivity, standardizing on a workflow within an organization or team is quite important. It gets everyone on the same page and on-boarding new comers is easier. Using git is one of such workflow.

It all start with a git clone somewhere.

git clone git@github.com:nuecho/rivr.git

You’re now ready to move forward to the next level of git workflow kungfu so here you go :-)

Step 1

I would highly recommend (close to enforce) you to go with smaller PR/MR targeting specific feature or fix and identifying the branch name as such using a prefix of either one of feature-, fix-, chore- along with associated ticket/issue id and a descriptive suffix.

*feature-NUBOT-35-minimal-help-system
 fix-NUBOT-610-wait-on-clone
 chore-NUBOT-550-update-auth0-deps

Before you go on with any change, ask yourself: what are my intent? Intent should be tied in some way to an issue, which is either a feature, a fix or a chore, where chore is essentially grunt work that is... not a feature nor a fix (!), in order to fulfill it. If there is no fulfillment objective, it either means that you’re doing something that is not planned, or that something else as come up (bug!) and should be reflected to the issue tracking (i.e. create a new issue).

Ready? Go!

git checkout -b fix-NUBOT-560-unhandled-popover-dismiss

Step 2

Now it’s time to get shit done. Hack your way in. At any moment, you may feel like committing some changes:

git add app/js/behaviours/help/help.hbs
git commit -m "Fixes NUBOT-560 transformed button into anchor"

But wait. What’s in your commit message? A commit message is your time travel guide. Make sure it conveys meaningful information. Example of anti-patterns include “cleaning”, “partial commit”, “css tweak”, or “wip”. Ideally your commit message include mention of issue/ticket id, a short one-liner about the change in itself and potentially bullet form details.

At some point in your development process, you should tidy up your workspace and squash commits togethers so that once merged into master, it doesn’t clutter the history with intermediary information. Enter interactive rebase:

git rebase -i 476fda^

Looking good! This way, it gets easier to review, easier to quickly integrate, easier to track progress over time. As a bonus, you get a really nice git history, with self-explanatory branch merge points and automatic issue/commit linking.

Step 3

Time to push over and share your work. But first, make sure your branch is current and up-to-date with master:

git rebase master

Yeah. We rebase, we don’t merge from. Don’t share you’re development branch and you won’t get into trouble. The repo will receive a nice and clean history.

At this stage, you might have conflicts. Resolve and proceed. Note that since you’ll be rebasing, the operation will re-apply all of your commits onto the HEAD of master, one after the other. In doing so, conflict may arise in every step of the way (but you’ve already squashed your commits right so it shouldn’t be a big deal right?) In any case, to facilitate conflict resolutions, enabling rerere configuration is highly recommended.

git config --global rerere.enabled true

Alright, share your work:

git push origin fix-NUBOT-560-unhandled-popover-dismiss #--force

Note that if you’ve push over any prior work on this branch and that you’ve modified your current branch history (with rebase or rebase -i), you’ll need to -f (force) your push (as it won’t be fast-forward).

Step 4

Review time! Code review is where you get feedback on your work: async pair programming. However, review is certainly not a replacement for unit testing nor upfront architectural design. Reviewer will be looking for code styling issues, potential bugs, patterns or library usage. Reviews are multi-facetted: knowledge transfer and learning craftsmanship from each others.

During the process, implementation details will be discussed and argued on. Disputes are most likely to arise. Stay calm. While some comments may appear a bit dry (“what’s that for?” “find another variable name.”), everything should be done respectfully. In any case, you can always reach out to other peers (at mentions) for input or psychological support (kidding). From time to time, a discussion may bring in change to general practice that would be reflected back to associated style guide. That’s how we evolve.

For any PR/MR featuring a UI modification/addition, we should also attach a screenshot (animated gif anyone?) of the actual modification (either zoom in or out depending on the nature of the change).

As part of the PR/MR, a build event should be triggered onto our continuous build server, where failing build can’t be merged onto master, acting as some quality gate.

At some point in a distant future, we’d like to auto-deploy once an MR has been approved and merged back to master where any staged releases would be considered for a prod release, as part of a continuous release pipeline. Hence, it remains paramount to have standalone commits, and only merge into master either fully working/implemented feature or opt-in facilities through feature flags (which is a whole subject on its own that we shall revisit shortly). That being said, we’re not there yet, and we still have much thinking in this regard but we have to have that mindset already.