Skip to main content

Git

Setup#

Github#

SSH Key#

  • Setting up a SSH key by following generating_github_ssh_key.
  • Run
    git config --global url.ssh://git@github.com/.insteadOf https://github.com/

Personal Access Token#

Repository#

Remote#

  • Repositories should be configured to automatically delete head branches. This helps keep our repositories clean!
  • Repositories should be configured for the main branch (typically master or main) to be a protected branch, configured to require linear history. This enforces that our history remains clean, and helps ensure changes can be easily reversed.
  • Repositories should be configured to allow rebase merging. This is the standard practice here at Thanx, however note that we should ensure that we squash our commits before we rebase. Often this involves squashing all commits on the head branch into a single commit, but not always! The important thing is that all commits are meaningful and contain logically connected changes - the pull request author should use their discretion to decide what commits to include. The goal here is to avoid small "wip"/"fix" commits from muddying the commit history of our base branches.
  • Repositories can be optionally configured to allow squash merging. This practice is a simpler alternative to squashing then rebasing, which can avoid human error (namely the pull request author forgetting to squash before rebasing). This merge strategy means that each pull request results in one commit in the base branch.

Local#

We maintain a linear git history across all our repositories. When merging changes, for most changes we squash and rebase. In circumstances where there is a large feature branch and preserving the history and authorship is required, we rebase and perform a merge commit labeled with the initiative or epic name.

  • Clone the repository
  • Checkout a new branch following the naming convention listed here
  • Make the required changes.

Branch#

Workflow#

We have our CI set up to automatically trigger workflows on pushes to specific upstream branches. Most commonly, these are our workflow branches:

  • upstream/production - deploy to production
  • upstream/sandbox - deploy to sandbox
  • upstream/staging - deploy to staging
  • upstream/ops-production - apply production terraform changes
  • upstream/ops-sandbox - apply sandbox terraform changes
  • upstream/ops-staging - apply stagging terraform changes

See Terraform docs for more information on applying Terraform changes.

Naming Convention#

Branch name should be the Jira ticket number if applicable, e.g KEY-000.

Commit#

We are heavily following commit message Guidelines, includes:

Format#

KEY-000. Capitalized, short (<= 50 characters).

This enables Jira to display the commit activity on the given ticket Summary should be less than 50 characters or less. More detailed explanatory text following if necessary, wrapped at 72 characters. Explanatory text should be separated from the summary with a line break.

Details should not be a list of all the squashed commit summaries, but additional context about the included changes.

Pull Request#

  • After finishing changes, open PR against upstream/master
  • Make sure CL/CI passes at this stage and resolves any potential conflicts.

Review#

Once PR is open, you can requested engineers for review.

  • Add everyone you want to review your PR as a Reviewer (includes optional reviewers)
  • If someone is required to review the PR, add them as an Assignee as well

If there are any changes required, make them, push changes back up to your fork's feature branch, wait for CI to turn green, and re-request the engineer.

After the PR is approved, it's the responsibility of the PR creator to merge the change into upstream/master.