Authors:

• Thomas Burleson, Solutions Architect
• Copyright 2021 - All rights reserved

GitOps: Top 10 Rules

Using Git properly is essential for successful web-application development and CI/CD. The best practices for GitFlow have been codified and condensed into 10 Essential Rules:

1. Use GitFlow strategies
2. Use Locked Branches
3. Rebase Often
4. Use Fast-Forward Merge
5. Use Commit Conventions
6. Use a Code Review process
7. Improve your Log History
8. Don't commit Dependencies
9. Use Prettier
10. Use README(s)

These ^ rules are sorted in highest priority and are detailed in the following sections.

Hint: Click a link above to speed-jump to the details for that rule.

(1) Use GitFlow Strategy

Unlike Trunk-based Git development, the Gitflow workflow defines strict branching models designed around pull-requests and multi-team project releases.

Main branches

• origin/master is the main branch where the source code of HEAD always reflects the current production-release.

• origin/develop is the main development branch where the source code of HEAD always reflects the latest integrated development changes; ready for the next QA release. Some would call this the “integration branch”.

This is where any automatic nightly builds are built from.

• origin/release is the QA branch used to perform acceptance, end-2-end testing, and other checks required before production release.

When changes are merged back into origin/master, this is a new production release by definition. This should be very strict process in which a Git hook script is used to automatically build and roll-out to the production servers everytime there is a commit on origin/master.

Only by using Pull-Requests can code be committed to origin/master… and only from the origin/release or origin/hotfixes branches. The Git repository settings should require production-release-manager approval to merge PRs into master.

Feature branches

• origin/feature/<xxx> are the branches in which all sprint work is performed. Feature-work changes can only be merged into origin/develop with Pull Requests. Long-lived feature branches should follow rule (3) Rebasing Often.

  • Automated CI will not triggered/performed on Feature branches.
  • Automated CI tests will be triggered for all Pull Requests.
  • Developers are not allowed to push commits direct to origin/master, origin/develop, or origin/release.

All developers should use the same repository for feature-based work. Developers should not fork the repository. While Forking provides significant upstream repository-benefits, the origin + upstream relationships complicates feature-based development.

(2) Use Locked Branches

All developer sprint-work will be performed in the origin/feature/<xxx> branches (or origin/hotfixes). Only these two (2) branches will support direct-push commits.

To enforce the Merge by Pull-Request process, the branches master, develop, and release should be locked to prevent direct push commits.

• All developer changes are restricted to origin/feature/** or origin/hotfix/**
• Only origin/feature/** & origin/hotfix/** branches support direct commit pushes
• All other branches require Pull Request processes to add commits (merges with squash, fast-forward)

(3) Rebase Often

Developers should always use git pull --rebase origin <branch> to insert all origin changes below the timeline of their current changes.

Developers can also use git rebase <with-source-branch> to rebase with a local branch (instead of the remote origin).

For feature-based work, the local feature-branch should be rebased (a) daily and (b) before all updates to the origin PR branch.

The following commands should be used:

• git pull --rebase origin develop …to update local code with origin changes.
• npm run build & npm test:affected & npm run lint …to confirm everything is still working.

To reduce local development friction, teams may elect to merge all PRs with automated rebase, squash, and fast-forward merges. The negative impact of this automation will limit each PR to one (1) single commit. As such, this approach is not recommended.

Feature branches can rebase locally: git pull --rebase origin develop.

Conflicts

Rebasing will inevitably produce conflicts that must be resolved. This is especially true for branches with many "change" commits. To reduce conflict-friction, developers should FIRST squash their new commits to 1..n logical commits.

If you do not want to customize the squash process then use git pull --rebase --autosquash origin/<branch>.

Squashing your own commits should facilitate conflict resolution when a git pull --rebase <branch> is susbsequently used.

---

Since rebase rewrites the target branch SHA history below your current branches changes… a git push -f will be required to update the remote origin branch.

---

Summary

Rebasing ensures that your feature changes are based on ALL current origin/develop changes.

• All Pull Requests should be rebased locally before pushing updates (to the PR branch).
• After rebasing:
  1. Locally perform a full cycle of 'build, test, lint'
  2. Must use git push -f origin <branch> to force push your rebased changes.
  3. CI will auto-run the same when the associated PR is updated.

Important: Force pushing should ONLY be used for your PR branch.

Full details: Pull-Request Best Practices (pending)

(4) Use Fast-Forward Merge

Your Pull Request has been rebased, commits squashed, pushed to origin, and all CI tests and checks are passing. After code reviews, reviewer approvals and LGTMs… it is time to merge your PR to origin/develop.

A Fast-Forward merge will ensure that origin/develop retains a flat commit history… without any cluttering 3-way merge information. Because this FF-M strategy moves the PR branch's commits to the origin/develop branch, you'll still see all commits on the Commits page.

Using "Fast-Forward Merge" supports PRs with more than 1 commit. This is another reason for authors to properly squash their commits to a logic set.

After the PR Merge…

The repository settings should be set to auto-archive the origin branch associated with a merged PR. Developers should also perform the following three (3) steps to update their local repository branches:

1. Checkout the develop branch: git checkout develop -f
2. Update develop with the latest origin version: git pull --ff origin master
3. Delete the local PR branch: git branch -D <PR branch>

(5) Use Commit Conventions

Why are conformance to Commit Conventions critical?

Development best practices use processes to auto-generate Release ChangeLogs from the commit history. And commit conventions are the key to ChangeLog auto-generations.

e.g.

Commit conventions promote concise, contextual commit messages that are easy to scan in change logs and project history. Using commit conventions [with squashing + rebasing], your Git Log history will be succinct and easy to manage.

e.g.

Commit Convention Details

The recommed conventions follow Google's Angular Guidelines regarding git commit message formats. Use the link below to jump to the Appendix section for full details:

Full details: Commit Conventions

(6) Require a Code Review process

A proper code review insures quality and provides a great mentoring opportunity.

Code changes are merged into origin/develop only with Pull Requests

Before a code review is started, the PR should include:

• An initial label PR: Ready for Review
• A PR body has clear description (images optional)
• A PR body with reference to Jira issue & other reference links.
• Code rebased from origin/develop
• Commits squashed to 1 or more logical commits
• At least 1 person (2 preferred) requested to review
• All CI processes passing: ( build, tests, e2e, lint )
• Assign CodeOwners and require review sign-off on PRs

All Pull Requests must have reviewer approval before a PR is ready for merge. PR Authors are never allowed to merge their own PRs.

Reviewers should avoid subjective criticisms and attempt to provide all feedback in a single review pass. After Code Reviews, approvals and LGTMs, it is time to merge your PR to origin/develop.

Full details: Git Code Reviews. (pending)

(7) Improved Git Logs

Developers want terminal tools to view log history in concise, compacted formats.

With traditional merge or pull approaches, the Git timeline gets distorted and polluted with unwanted merge information. Repository log history can produce radically different outputs.

git lg    # show compact history 

Here is project history for teams NOT following best practices:

Here the team is following bes practices: Rebasing, Squash, and Commit Conventions. These all work togehter to ensure the git history will be flat, clean, and concise.

A flat timeline (eg commit history) is another important factor to the auto-generation of ChangeLogs. Notice how the use of Commit Conventions helps create a clear, concise log history (above).

Full details: Customizing your Git Log

(8) Don't commit Dependencies

Always use a .gitignore file to exclude specific artifacts for source control management.

Full Details here: Recommended .gitIgnore Settings

(9) Use Prettier

Use prettier to auto-format all files during save. Use Prettier to minimize commit-change white noise.

• Use nx format:write to format all files in project.
• Enable Format on Save options in your IDE.

Consistent use of Prettier will ensure your Pull Requests will only show diffs for content changes instead of style/format changes.

.prettierrc

{
  "singleQuote": true,
  "useTabs": false,
  "printWidth": 120,
  "tabWidth": 2
}

Jump to: Prettier Options

(10) Use README(s)

A Repository will have at least one (1) README.md… but may contain others for specific folders or packages. The intent for each README is to convey information (and images if available) to show the purpose of the repository, package, or directoy.

Do not use the default, generated README.

README documents should be hyperlinked to support easy navigation.

Badges should be used in the root project README to highlight version, CI status, and more

Jump to: Badge Options.

Appendix

Within this appendix are details for various options and recommendations

• Customized Git Logs
• Commit Message Conventions
• Developer Tooling
• .gitignore settings