Tools

We actively encourage and prefer you to use Github Desktop as opposed to Git via CLI, or via an alternative GUI app. Our organization is Github-based, and the tools provided with Github Desktop make managing your work as easy and fast as using Github itself. This is something you'll come to appreciate and enjoy - particularly as you move between multiple projects concurrently.

Our Feature Branch workflow

We use a feature branch workflow on all projects. The core idea behind the Feature Branch Workflow is that all feature development should take place in a dedicated branch instead of the master branch. This encapsulation makes it easy for multiple developers to work on a particular feature without disturbing the main codebase. It also means the master branch will never contain broken code, which is a huge advantage for continuous integration environments (like Netlify).

Encapsulating feature development also makes it possible to leverage pull requests, which are a way to initiate discussions around a branch. They give other developers the opportunity to sign off on a feature before it gets integrated into the official project. Or, if you get stuck in the middle of a feature, you can open a pull request asking for suggestions from your colleagues. The point is, pull requests make it incredibly easy for your team to comment on each other’s work.

How it works

The Feature Branch Workflow assumes a central repository, and master represents the official project history. Instead of committing directly on the local master branch, you should create a new branch every time you start work on a new feature. Feature branches should have descriptive names, like animated-menu-items or issue-#1061. The idea is to give a clear, highly-focused purpose to each branch. Git makes no technical distinction between the master branch and feature branches, so developers can edit, stage, and commit changes to a feature branch.

In addition, feature branches can (and should) be pushed to the central repository. This makes it possible to share a feature with other developers without touching any official code. It is also important to your supervisors, and our clients - when Branch Deploys are enabled on Netlify, both your supervisor and client can view the latest building version of any live code you've pushed to the branch.

Start with the master branch

All feature branches are created off the latest code state of a project. In Github Desktop, create a new branch based on the main branch, and give it a sensible name that indicates the feature/task you are working on. Switch to this branch once it is created.

Update, add, commit, and push changes

On this branch, edit, stage, and commit changes in the usual fashion, building up the feature with as many commits as necessary. Work on the feature and make commits like you would any time you use Git. When ready, push your commits, updating the branch on Github.

Submit PR

Push feature branch to remote, and submit a PR.

It’s essential to push the feature branch up to the central repository. This serves as a convenient backup, promotes collaboration, and allows your supervisor and client to see your work-in-progess. Once you're happy with your work, you can submit a Pull Request to allow your work to be folded into the project.

Resolve feedback

Your supervisor/teammates will comment on and approve the pushed commits. Resolve their comments locally, commit, and push the suggested changes to Github. Your updates appear in the pull request.

Merge your pull request

Before you merge, you may have to resolve merge conflicts if others have made changes to the repo. When your pull request is approved and conflict-free, you can add your code to the master branch. You'll need to merge the pull request in Github via the online GUI.

Pull requests

Aside from isolating feature development, branches make it possible to discuss changes via pull requests. Once someone completes a feature, they don’t immediately merge it into master. Instead, they push the feature branch to the central server and file a pull request asking to merge their additions into master. This gives other developers an opportunity to review the changes before they become a part of the main codebase.

Code review is a major benefit of pull requests, but they’re actually designed to be a generic way to talk about code. You can think of pull requests as a discussion dedicated to a particular branch. This means that they can also be used much earlier in the development process. For example, if a developer needs help with a particular feature, all they have to do is file a pull request. Interested parties will be notified automatically, and they’ll be able to see the question right next to the relevant commits.