During my career as a software developer, I had the privilege of working in a couple of very talented teams. All of those teams were different in the way they handled contributions to repositories and when I compare these, it leads me to believe that it is very important to the overall output of the team.
At Sudolabs, we have a very specific process for contributing to our projects. This is the
CONTRIBUTING.md that we use for almost every project we work on:
Git - the version control system is not merely a cloud-based backup for code, but - if used wisely - a powerful tool to make developer's life better. Even more so, when there's entire team of devs collaborating on a project.
An effective git / GitHub workflow has multiple benefits:
However, some kind of standardized workflow has to come into play to achieve this.
Our git / GitHub workflow consists of couple of steps:
Let's explore it one by one.
An Issue represents a single task to be done. Think of it like an item in a To-Do list.
You can either have an Issue already assigned to you, or you can create a new one.
If you are creating an issue, make sure to follow this recommendation:
A good issue consists of
-to separate "where" from "what"
Status: Up for grabslabel, so anybody can take it up.
Status: Blockedmeans the progress on this issue is blocked by external dependency/force
Status: Duplicatemeans the issue is the same as the one already opened
Status: Feedback neededmeans that assignee needs your opinion
Status: In progressmeans that assignee has started to work on the issue
Status: Rejectedmeans the issue was rejected due to reason specified by the last comment e.g. duplicated, already solved somewhere else
Status: Review neededmeans the issue is addressed by a Pull Request, that will eventually close it
Status: Testingmeans the issue is for test-related things
Status: Up for grabsmeans anybody can pick it up; usually issues such labelled have nobody assigned
Type: Bugmeans the issue is a bug
Type: Developmentmeans the issue is for development-related things e.g. documentation, libraries
Type: Enhancementmeans the issue improves existing feature
Type: Featuremeans the issue is a new feature
Deploy target: <version>means in which version the issue will be deployed
When creating a new issue which is not connected to you directly, leave
Do not work on issues with no sprint assigned.
⚠️ You should never commit directly to
We use Git Flow branching model, which (apart from many things) suggests using
feature branch prefixes for development.
So if you are
Deploy target: <version>of the issue.
Deploy target: v1label refers to
Deploy target: v2label refers to
release/*), and start your branch name with
As an added benefit, most git GUIs can display such prefixed branches in folder-like structure, prefix being the folder name.
Read this: How to Write a Git Commit Message
fixes a typo
Fix a typo)
Don't forget to push your branch to the remote, so you can follow up with the next step.
A Pull Request (PR) should ideally be named after the Issue it addresses.
However, there might be cases where the changes you make are much more exhaustive than the Issue they fix (e.g. an Issue "Make content scrollable on small devices" might require a refactor of current layout implementation). In this case it's better to name the PR after the changes you make, instead of after an Issue/s it closes.
Furthermore, make use of GitHub's Closing Keywords in your PR's description:
You can include keywords in your pull request descriptions, as well as commit messages, to automatically close issues in GitHub. The following keywords, followed by an issue number, will close the issue:
For example, to close an issue numbered 123, you could use the phrase "Closes #123" or > "Closes: #123" in your pull request description or commit message. Once the branch is merged into the default branch, the issue will close.
Reviewers are added automatically thanks to the CODEOWNERS, so you don't need to worry about it.
Once you submit your PR, don't forget to add
ready for review label to signalize other devs they can review your changes.
If you work on something on the PR, change the label to
in progress to prevent others from reviewing code that you are in process of changing.
After you address reviewer's suggestion / comment, always leave a reply with the hash of the commit containing your changes e.g.
300c2ab. This way reviewers can quickly see and check your implementation.
And last but not least, do not add milestones to the PR, they are only for the Issues.
Commits with name like
WIP should never make it to the main branch - they're not helpful at all.
If your branch has commits like that, or other commits that don't have a reason to exist separately, you should squash them into fewer commits (or even one) with interactive rebase.
If you want to save your work-in-progress, use git stash feature.
If there is a serious reason (eg. half-done change, that needs to get into the main branch), always include a sensible commit title after the
...at least 2 people approved your PR.
⚠️ Only the creator of PR can merge it to prevent issues with translations.
Don't forget to delete the branch after it's merged, to keep it clean & tidy around here.
Courtesy of Sebastián Andil, my colleague, who wrote down our process in this guide.