Opinionated guide to version control

I have worked with various different version control workflow practices and feel like I should share my personal workflow that works for me.

Link your tasks to a tracking ticket.

First, figure out the tracking system you are using for work. Different companies use different tracking systems. Github issues are amazing and my personal favorite. There is also JIRA (which I don’t like much at all), but is used quite a bit more in my experience. You will generally have some ID like [MAT-512] that you can reference your pull requests later.

Github makes this super easy if you are using Github issues. You can simply even reference the #512 anywhere in your comments and there is a link achieved.

Yes, this can get complicated where your code changes might address multiple tickets. Maybe do [MAT-512, MAT-513] for instance.

This will keep your Technical Program Manager, Team Lead, or Scrum Master very happy.

Create code changes against a fork of the repository

When I work on a new code base, I typically just “fork” the repository in Github. There are many reasons for that:

• I might not have access to push new branches to the upstream repo.
• Even if I did, I might not want to add various feature branches to that upstream repo for various reasons.
• Keeps things clean on the upstream- how many of your see all these graveyard branches on master??
• Exceptions: If you are the only one working on the repo just do whatever you want. Or if you are setting up CI/CD automated pipelines you’ll want to be working from upstream.

How should I create my branch?

You can file your branches into buckets like directories. For instance hotfix/MAT-312 or features/MAT-512 or I actually prefer hotfix/312-fix-segfault.

All new code should just land in master.

I have seen a lot of convoluted workflows. One I’ll bring out right now is the master-develop paradigm. I never understood the popularity of this “develop” branch. With this paradigm, you create feature branches, you merge to develop. You test it and you eventually merge to master when you feel it’s stable enough.

Yes, there might be many workflows that work for your team and that’s the great thing about the power of git. But let’s instead simplify this- but add some Git magic to it:

• Add PR’s should be staged against the master branch
• If you are cutting a release, you can place a git tag with the version on that last commit.
• If you have to maintain that version without breaking compatibility simply branch from that tag and name the branch your version.
• If you have a release, you can branch early- have people contribute to that branch

What do I do if master changed and I have merge conflicts??

If you can’t merge your PR anymore but used to be able to- some other PR was merged that touched the same files as you. For a revision of your PR, you have to choose to use their file as is, use your file as is, or do a complicated merge between the two to incorporate both changes.

For example, in this case, I usually just merge upstream/master to fork/512-add-bert. I resolve the merge conflicts in my editor like VS Code. And commit and push it back.

What if I’m still working on something?

Yes, work in progress or WIP is very typical. I recommend (especially when working with others) to create a pull request early. But then demote it to a “draft”. That will allow you to make edits but still allow others to comment on it.

Reviewers shouldn’t merge the PR

This is controversial and based on the access privileges that are on the repository.

Most times, the author will file a PR, get feedback, and introduce feedback. The problem is that if there is feedback but the reviewer goes ahead and merges the branch. That’s a big problem. It’s best to just have the author proceed to address the feedback

Random stuff

I really like to set up GPG on my commits. It’s easy to do!