Collaboration Principles

Collaboration Principles#

The usage of does not necessarily facilitate collaboration.

It all depends on how you are using !

Even though with you can track and document strictly all changes in a repository, simply using does not yet make you a good collaborator.

What exactly are good usage patterns is a well discussed and opinionated subject.

Instead of contributing to this discussion we will point out a few principles that simplify interactions mediated by .

Healthy Reference#

A pre-requirement to successfully develop any change, or new feature, is to be able to depart from a functional state.

In the -context this translates to:

At any time all developers know 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 to contain errors

  • be functional

A successful collaboration and development strategy should cultivate healthy states, leading to the first set of best practices:

Best Practice (1/4)#

Keep a healthy 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 reference location for the reference branch.

  • Identify one branch on one location to be the main reference1While 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 reference location for the reference branch.

  • Never develop directly on the main reference

  • Never modify shared history

  • Try to consolidate branches whenever possible

  • 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.

  • …

With any edit can lead to a commit and a branch can consist of any sequence of commits. It is up to the developer to associate branches with specific subjects or tasks and distribute commits onto these branches in a meaningful manner.

Following the history of a repository becomes easier if the single branches incorporate some subject specificity, leading to a further set of best practices:

Best Practice (2/4)#

Use branches to isolate changes

  • Agglomerate commits with a similar subject or purpose in a common branch

  • Incorporate branches with completed purpose

Meaningful Steps#

Incremental change is 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 up to the developer to decide how many or few edits go into a commit and, similarly to the Separate subjects, what these changes are about.

In addition, commits make up the elementary steps in a git history and can easily be:

  • undone (see e.g. git revert )

  • applied onto other branches

Best Practice (3/4)#

Commit small but complete changes

  • Decide what changes to include in a commit (use git add -p)

  • Make a commit as specific as possible

  • Write commit messages that specify the purpose of the commit

  • Include as few as possible changes into a commit

Flag States#

An easily distinguishable reference facilitates orientation.

With this translates to:

Documenting states is equally important to documenting changes

As a developer working the most noticeable documentation activity is writing commit messages. Since commit messages strive to explain the introduced changes it can quickly become cumbersome to identify particular states of a repository when solely relying on commit messages. Essentially, when writing only commit messages the state of a repository remains undocumented.

As a consequence it can become difficult to identify healthy states which is something that can be circumvented by the use of tags:

Best Practice (4/4)#

Regularly tag good states

  • Tag particular states (see git tag )

  • Use a meaningful versioning framework to describe states (e.g. semver )

Content