So you’ve moved to Git because all the cool kids are doing it. You’re still doing your old workflow, just with added complexity, and you’re wondering what all the hype is about.
There are lots of different ways of using Git. They all involve a lot of branches, because that is the best way to have lots of people working on the same code base without creating a giant mess. Let’s build a simple workflow for a team of 1-5 people, starting with a simple setup for single-dev teams and tweaking it until it’s enterprise-ready.
Master and Development
Most Git setups will have these two branches. master is the code that lives on your production server. development is the stuff that’s finished and will be included in the next scheduled release.
This is the setup for my one-person hobby projects. I commit new stuff directly to development (often unfinished), and when I’ve got a stable set of stuff I merge it into master and pull it onto the server.
Benefits: Your production code is separate from the new stuff. If you need to fix a bug urgently, you can do it on the master branch and pull that onto production, without simultaneously releasing your new features.
Drawbacks: Your development branch is still a dumping ground for everything that isn’t production-ready. As you add more devs it will become unstable and your team might fall back into the anti-pattern of not being allowed to commit anything just before the release.
Branch Per Feature
As above, but every feature (or improvement or bug fix) is developed in its own branch. Once it’s ready to go, its creator merges it into development or master as appropriate.
If you have to make a production bug fix, you make a branch off master. Give it a meaningful name, like bugfix-1234 (where 1234 is a ticket number) or bugfix-3.2.1 (where 3.2 is your release number and this is the first bug fix). Do your work in this branch, committing as many times as you like, and then merge it into master once you’re done.
For other work, you make a branch off development. Meaningful and consistent names are still very helpful. This is often just a ticket number (1234), or a ticket number with a brief description (1234-new-datatables). Once it’s been approved for the next release, it gets merged back into development.
Benefits: Half-finished code is not in your development branch. If devs are switching between tasks, they can commit what they’ve got without breaking things for others. Ditto if you want to transfer a half-finished task from one dev to another. Devs can check out each other’s completed features to test and review, or to demo to product owners.
Drawback: The review process is informal (a dev might ask a colleague to look at something before merging, but there’s nothing stopping them from skipping this step) and not particularly transparent (difficult to identify whether a task was reviewed, and by who). Useful feedback from reviews is only communicated between the reviewer and reviewee.
Pull Requests
As above, but when a dev has finished a task, they raise a pull request in GitHub to indicate that it is ready for review.
A pull request is an assertion that a piece of code is ready to be merged into development. The list of open pull requests can be seen in the GitHub UI. Senior devs can check this regularly and review the tasks that are waiting to be merged. They make comments on the pull requests which all devs on the team can see. For new features they will probably also want to check the code out and see it in action, but this may not be necessary for minor tweaks and bug fixes.
The dev addresses the reviewer’s comments, pushes their changes, and adds a note to the PR to say that they’ve fixed it. Once the reviewer is happy with the code, they click a button on GitHub and it gets merged into development.
Benefits: Review process becomes asynchronous (devs aren’t privately messaging each other for reviews) and transparent (because everybody can see what’s been said). New devs can learn a lot about the system and the team’s coding conventions by browsing open PRs. The archive of closed PRs doubles as a library of blueprints for future work, which can also be very helpful for juniors and newcomers.
Drawbacks: GitHub PR notification spam (but you can turn down your notification settings so that you only get emails about the stuff that’s relevant to you). Can lead to painful multi-round reviews where the dev deals with one reviewer’s feedback, but then gets more suggestions from another.
Automated Code Quality Checks
The leading Git providers have a range of tools to help prevent low-quality code from making it into your code base.
On GitHub this takes the form of GitHub Actions, which allows you to configure workflows which are triggered automatically by certain events. A common usage of these is to perform automated checks (such as running a linter or a set of unit tests) every time a new pull request is raised.
This is only scratching the surface of what you can do with Actions. There are almost 6000 actions available in the GitHub Marketplace, and a variety of other events you can trigger workflows on – you can even schedule them like cron jobs.
Benefits: Automatic linting saves reviewers from wasting their time pointing out basic style violations. Automatic test builds mean you can be confident that code going into the development branch won’t break anything – although of course this promise is only as good as your test coverage!
Drawbacks: Automated processes are not a substitute for human judgement.
Summary
Git can do a lot to solve common collaboration headaches. You don’t have to change everything about your workflow at once, but if you recognise any of the pain points above hopefully this guide will help you to address them.
Your team’s GitHub workflow should be reviewed regularly, as should the larger process of how a task goes from an idea in somebody’s brain to a completed, deployed feature.