Git Standards

These are the conventions used across Push projects. None of them are clever. Their value is in being applied the same way every time, so that anyone can open a repository and know where they are.

Naming repositories🔗

• Use snake or kebab case and no spaces. Lowercase letters with underscores or hyphens read well and avoid URL-encoding problems.
• Name for the permalink. A repository name should survive for the life of the content, so choose one you will not need to change.
• Prefix with the organisation. MSFT for Microsoft, NEWCO for a new company. The prefix makes ownership obvious at a glance.
• Domain first, then topic. Finance.Billing or Retail.Inventory says what the code is for before it says what it is.
• Separate infrastructure and operations. Keep infrastructure and operational content in their own repositories so each one has a single purpose.
• Support a code wiki. Knowledge management is first-class. Give technical writers somewhere to document the code alongside it.

Templates🔗

Branching🔗

Work is separated into branches by purpose and stage.¹

• main is the stable, production-ready branch. No direct commits. Production builds come only from here, after the work has been tested and reviewed elsewhere.
• Feature branches (feat/name-of-the-feature) are created per feature. When the feature is complete it merges to main through the agreed conditions and pipelines, which normally means deploying through development, test and possibly user-acceptance environments on the way.
• Story branches (story/name-of-task) branch from a feature branch for smaller tasks. Builds from story branches deploy to development and test. A finished story merges back into its feature branch.
• Hotfix branches (hotfix/some-name) are rare. They branch from main when a critical production issue is found. Once the hotfix ships, every feature branch takes the update from main so the same issue is not reintroduced.

Pipelines🔗

Restrict which branches can deploy to which environments. Without that rule, branch approvers receive an approval email for every build, and once the number of pending approvals grows past a threshold, automatic builds stop.

Commit messages🔗

All commit messages are in English so that anyone can contribute.

We use Conventional Commits: the message reads as a sentence whose first word is the type of change, followed by a description.²

Good

git commit -m "feat: allow provided config object to extend configs"
git commit -m "docs: correct spelling of CHANGELOG"
git commit -m "feat(lang): add the Portuguese language"

Bad

git commit -m "Add placeholder on input"

Further reading🔗

• A successful Git branching model by Vincent Driessen. The original description of branching by stage, tagging versions and merging in a way that stays maintainable.
• Raygun: Git workflow tips. Setting up a workflow, branching and merging, resolving conflicts and handling code review.
• GitKraken: Git branch strategy best practices. A plain guide to branches, merges, conflicts and collaboration.