Collaboration Principles#
The usage of does not necessarily facilitate collaboration.
It all depends on how you are using !
Even though allows you to strictly track and document all changes in a repository, simply using does not automatically make you a good collaborator.
What defines good practices is a widely discussed and often opinionated topic.
Rather than adding to this debate, we will highlight a few principles that simplify interactions facilitated by .
Healthy Reference#
A prerequisite for successfully developing any change or new feature is starting from a functional state.
In the context of -, this means that:
At any time, all developers are aware of a specific commit on a specific branch that represents a healthy state.
More precisely, this state should:
Contain most of the history, i.e. as recent as possible.
Have a minimal chance of containing errors.
Be functional, meaning it should be possible to build and run the software.
A successful collaboration and development strategy should cultivate these healthy states, leading to the following set of best practices:
Best Practice (1/4)#
-
1While is a distributed version control system, it is usually not decentralized in practice: A repository typically has one upstream location (e.g. origin) which acts as a reference location for the reference branch.
Identify one branch on one location to be the main reference,1While is a distributed version control system, it is usually not decentralized in practice: A repository typically has one upstream location (e.g. origin) which acts as a reference location for the reference branch.
Never develop directly on the main reference,
Never modify shared history,
Try to consolidate branches whenever possible, and
Verify the functionality of the resulting state before you incorporate a branch into the main reference
Separate Changes#
Any storyline is easier to follow if it is split into chapters. Chapters provide the option to organize, pace, and develop a narrative.
A repository is no different:
Development should always be structured into manageable, independent pieces allowing for focused work, clear boundaries, and easy integration into the larger whole.
Typically, a repository contains various types of files and a developer performs various tasks, like:
adding new features,
refactoring existing code,
fixing typos,
completing the documentation,
etc.
With , any edit can lead to a commit, and a branch can consist of any sequence of commits. It is the developer’s responsability to associate branches with specific subjects or tasks and to distribute commits across these branches in a meaningful way.
Following the history of a repository becomes easier when individual branches have specific subjects, leading to this second set of best practices:
Best Practice (2/4)#
Group commits with a similar subject or purpose in a common branch.
Merge branches once their purpose is complete, for instance after finishing to develop a feature, fix a bug, or writing the documentation.
Meaningful Steps#
Incremental changes are easier to deal with if single increments are logical, self-contained but remain as lean as possible.
In the -world:
Incremental changes should introduce minimal, self-contained logical steps.
It is the developer’s choice how many edits to include in a commit and, as previously mentioned in the section “separate subjects, what these changes pertain to.
Additionally, commits reprensent the fundamental steps in a history and can easily be:
Undone (see e.g., git revert ),
Applied onto other branches.
Best Practice (3/4)#
Decide what changes to include in a commit (use
git add -p).Make a commit as specific as possible, i.e., include only changes that belong together.
2As a guideline, you can use the Conventional Commits specification.Write commit messages that specify the purpose of the commit 2As a guideline, you can use the Conventional Commits specification. .
Include as few changes as possible into a commit. Lots of changes make it harder to understand the purpose of the commit. Consider splitting the changes into multiple commits and use branches to isolate changes.
Flag States#
An easily distinguishable reference facilitates orientation.
With this translates to:
Documenting states is equally important to documenting changes.
As a developer, one of your primary tasks is to write clear and concise commit messages. These messages are crucial as they explain the changes made. However, relying solely on them can make it difficult to identify specific states of a repository. When writing only commit messages, the state of a repository remains undocumented. As a result, identifying healthy states can become challenging. However, this can easily be addressed using tags.