How to improve your GitHub workflow
AuthorAndrija Dvorski
DateJul 31, 2019
GitHub is a powerful tool that shouldn’t be used only to host your git repositories. It offers you a lot of additional functionalities with Issues, Pull Requests, Milestones and Projects.
In this post, I’ll go over some of the things and techniques you can do to improve your git/GitHub workflow. The things I’ll write here should also be applicable to other git hosting platforms.
Commits
Here’s the deal – everybody commits their code, but everyone commits differently. Some people do commits for every few lines of code, while some wait for a whole logical unit of code to be complete before committing. It’s very easy to start using git and get a hang of it, so people develop bad habits when it comes to committing, branching, and documenting their changes. You should work on this as soon as possible to get the most out of the version control.
To upgrade your workflow, you can follow this standard I use when it comes to git commit messages. The thing is – when something is standardized, it’s easier to expect what it’s about and it’s easier to write it.
The standard proposed is this:
<type>(<scope>): <subject> (<#issue>)
<BLANK LINE>
<body>Types
- feature
- bugfix
- docs
- style – formatting, missing semicolons…
- refactor
- test – if tests are added after a feature is implemented, otherwise you should commit them along with the feature
- chore – this one is related to maintaining
Scope
A scope should specify a place of the commit change. For example – validation, StorageService, etc. In most cases, this is the name of the feature (either a new one or one that’s already implemented).
Subject
- use an imperative form instead of temporal forms (perfect or present) – “change” instead of “changed” or “changes”
- do not add a dot (.) at the end
- capitalize the first letter
- good practice – when writing the commit subject, form it in a way so it completes the following statement: “If applied, this commit will…”
Body
This is where you should explain the change and your thinking process when you were implementing it. You don’t have to worry about tense or structure when writing the commit message, just express yourself clearly. You should also reference related pull request (PR) or Issue if applicable.
Example of the message
feature(storage): Postgres StorageService implementation (#13) I’ve implemented StorageService using Postgres, due to a change in Storage layer. PR #12 This will replace existing StorageService implementation and be responsible for storing model data in a database. I’ve deleted the previous implementation since it won't be used anymore.
The last thing I would like to mention about committing is that you should withhold pushing to remote unless you are finished and ready to merge, or there are multiple people working with you on the same branch. This is because it is easier to modify commits if they are not pushed yet.
Milestones
Milestones are the second big aspect I’d like to talk about. They are great if there is a bigger feature that needs to be released. GitHub enables you to divide it into multiple issues and pull requests that are all connected to the same milestone. After you clear all issues assigned to a milestone, you can make a pull request to master branch for it, finishing the milestone.
Issues
Okay, issues on GitHub are really useful. They are an easy way to provide context to your commits and pull requests without much effort. You should create an issue for every problem, feature, improvement or discussion related to the project. This is because issues provide a great backlog of past things done and discussed. It is a lot easier to put reasons and motivation for a change in the code into context if you have a git history with Issue and PR references in commit messages.
Issues also serve as references from commits and pull requests – by providing more context for understanding the changes in the code, we can more easily understand what particular problems and challenges were being solved.
For example, let’s say you found a change in the code you don’t quite understand. Instead of going around asking your colleagues, trying to piece together what they remember of the project, and ultimately getting only half of the picture behind the change, you could check out the Issue referenced in a particular git commit (if the commit message itself doesn’t provide enough context), see what was the origin of the problem, look up the PR that resolved that Issue and see the discussion of the code implemented to fix the change. I think this helps a lot more with debugging and code sanity.
Standards to follow
- title does not need to have the project title in issue title. (eg. “[project-name] This is an issue”. Except for mono-repo)
- don’t end title with a dot (.), question mark (?) is okay
- if it’s a problem, explain the problem and how/when it occurs in the issue body
- if it’s a feature, explain it and write proposed flow of the feature in the body
- if it’s a question/discussion, have a clear goal for it
- if applicable, assign it to a milestone
- label the issue accordingly
Labeling
Labeling provides great filtering capabilities for both open and closed issues on a project. If someone wishes to help with the refactoring of a project, they can easily filter by the refactor label and see issues that are related to refactoring. Also, labels are helpful when you want to look at an older issue of something, but you are not sure what exactly are you looking for. By filtering through labels, you can narrow down your search and be faster at finding the problem (and a solution) you need.
Referencing
Referencing issues from commits and pull requests is important to connect everything together. Issue is a starting point of a change, Pull Request is a proposed solution to the change, and the commit is the code implementing the proposed solution. Both Pull Request and commits should always have an issue connected to them.
If you push a commit that doesn’t have an issue referenced from it, you should’ve most likely written that change as an issue first.
Pull Requests
Pull Requests are one of the most important features that git version control enables, and GitHub gives you a really nice wrapper around them with code review features, tagging and discussion. Please watch out for any contribution guidelines when submitting a PR, and make sure to pay update documentation if you introduced changes that require it.
Rules
- every pull request should have an issue it attempts to provide a solution to
- there should be at least one approving review before merging
- you should not merge if CI fails – check what’s wrong, fix it and rerun the tests
- pushing additional commits to a previously approved PR should render previous approval invalid and new review should be required
- after merging, remember to remove the branch you just merged
Conclusion
While using version control and code review in itself is a huge improvement to your workflow and your code quality, you should strive to get the most out of the tools offered to you. All these things will help you as a developer to better communicate changes you introduce, but they’ll also help your team to understand these changes. You will also provide a lot more context for those same changes with more room for discussion, and you’ll also help with understanding historical reasons for the change and the debugging process. you’d like to discuss, share it with our team!
