Delivery Git

An overview of Git best practices regarding branch maintenance and pull requests.

Overview

In an effort to bring consistency to Kinetic Data’s git repositories, Kinetic Data developers have chosen to standardize various practices involving git, such as branch names, merging process, and branching flow.

Branch Naming Standards

Protected Branches

Protected branches are the working branches for the primary environments prior to project completion. When beginning a new customer bundle project, the two default protected branches should be set up:

· main - This is the primary development branch. Since, for the most part, developers work alone on projects, the main branch is all that's needed, as opposed to multiple staging (or environmental) branches. Any feature that's small enough to be completed in one or two sprints should be committed to the main branch via a PR.

· epic - This branch is used for large-scale feature work. The epic branch allows developers to work on large-scale projects (2+ sprints) that may require multiple feature branches to complete. The epic branch should never be committed to directly, and any changes should come from individual Pull Requests (PRs) to preserve the commit history in Git. Since individual PRs will be reviewed and approved as they are added to an epic branch, once it's ready to be added to the main protected branch, it can simply be rebased or merged without issue.

There can be additional protected branches (e.g. uat, demo) for a number of reasons. Naming conventions for protected branches should be either a single word or abbreviation and to the point of the reason for the branch. Since work flowing through protected branches should be distributed through the workflow process, there is no need to add additional information to the branch name.

Working Branches

Working branches will follow the naming standards:

· {CHANGE-TYPE}/{MONDAY-ID}-{DESCRIPTION}

{CHANGE-TYPE} is a broad description of the type of work being done. There are two working branch types: feature/ and hotfix/. feature is used for any working branch that is implementing new updates to the codebase. hotfix/ is used for any type of bug fixes or corrections to existing code or features that were already added to the main branch previously. {MONDAY-ID} allows devs to quickly view the original Monday ticket for the work being done in this branch. This allows easy handoffs of work as well as tracking within GitHub. {DESCRIPTION} is a shorthand description of what the branch changes cover. Providing a short description in a branch name allows a developer to quickly understand what the branch is for instead of having to first look it up in another tool.

Examples

feature/eventsourcing_submissions

hotfix/form_consolidation_searching

Merging Standards

Workflow

The best practice for new feature work or issues being resolved with a hotfix is to branch from main. This minimizes conflicts if changes occur in main while in a working branch. After completing the updates in the working branch, create a PR to merge the working branch back into main. Using this workflow should guarantee that only completed work (or very close to completed) is merged into the main branch for final testing. If the amount of work necessary is larger than the amount of work done within a normal feature branch, then use the epic branch. First, ensure the epic branch matches main, then create as many feature branches off epic as needed to complete the work. Note that the branching and PR strategies to and from the epic branch are the same as normal feature work to and from main. Once everything is working as intended in epic it can be rebased or merged back into main.

Rebasing

By default, merging branches into main should be done as a rebase to preserve commit history and make commits more easily digestible. Rebase merging helps to remove noisy merge commits that do not add value for reviewing history.

Squashing

In general, squashing should only be performed when a developer is on a fresh working branch, and the squashed commits would not create one very large commit that would be difficult to read through. An example of when squashing is a sound decision is if a new branch consists of only a few commits and the additional commits are for minor review changes, typos, etc, and would result in fewer commits with messages like “Fixed typos” or “Changed URL for test XYZ.” These are more guidelines than actual rules, however, and when it is best to squash is left up to individual developers' discretion when asking an approver for a pull request.

Pull Request and Code Review Practices

All code must go through a code review before being deployed to a protected branch. By policy, code cannot be merged into a protected branch by any means other than a pull request.

The one exception to this policy is merging/rebasing an upstream branch. For example, when we merge main into the upstream epic branch. This may be done manually via CLI if the process does not require substantial merge conflict corrections.

Creating a Pull Request

1. No developer who committed any code to the branch may be involved in merging or reviewing except to answer reviewer questions.

2. The Pull Request title must include the Monday ID and a brief description. For example, a good title would look like this: 4523601790: Updated Spring dependencies. The Monday ID provides a quick reference to the Monday item. The description should be more specific to the code - relevant information such as specific changes that, without background, may require additional context. In addition to notes related to the code, you may want to request a specific merge type, such as when you have a number of commits and want the branch squashed to a single commit.

3. Use Draft for multi-commit, ongoing pull requests. The primary situation here is when you have made an attempt at an issue but require a review to validate your work in order to continue.

4. The appropriate target branch must be specified and must be a protected branch.

Reviewing a Pull Request

If you are reviewing a Pull Request you must ensure that you are not an involved developer (committed any code) and that you have enough language and area knowledge to effectively review the request. Once you are ready to review, ensure that you have added yourself to the Reviewers section so that others (including the author) know that you’re interested in reviewing the PR. This helps the team know whether or not the issue is still looking for a reviewer and serves as a historical reference to which individuals were reviewing the code.

Reviewer's panel

The easiest way to review the code in the Pull Request is to use the Files Changed tab. This gives the best overall view of what the PR is changing. When reviewing, you will be evaluating the following:

1. Code quality - are there any obvious faults, missed exception handling, etc

2. Code style - are variables named appropriately, is the formatting sensible, etc.

3. Effective changes - do the functionality changes, changed/added dependencies, and general approach to solving the problem make sense and match our standards.

4. Functional testing - if necessary check out the branch, run the tests, and evaluate the code at runtime.

5. Destination branch - ensure that the protected branch the author requests is appropriate.

Functional testing isn’t always necessary for the reviewing. Many Pull Requests will not require the reviewer to checkout the branch and test it themselves. Two good ways to know if you should functionally test a PR: are the test suites able to effectively test most of the functionality, and just a gut sense that there are “too many moving parts” and a brief evaluation is necessary.

Once the code has been reviewed, you can comment, request changes, or approve the code. When requesting changes or commenting you can either use the review dropdown or you can comment inline. Commenting or requesting changes inline is preferred as it helps the author with context.

(Start a review).

Approve, comment, or request changes on the whole PR.

Comment (Add single comment) or Request Changes (Start a review).

Once the PR is approved, you can merge it at any time. When choosing which way to merge there are a few guidelines.

1. Always assume Rebase and merge unless…

2. There are a lot of commits, in which case you may want to Squash and merge.

3. The author of the PR may want a specific merge type, so check the description or ask them.

When using Squash and merge, keep the commit messages in the top input box and use the second input box if you have additional commit messages to add.

*These instructions are based on the engineering documents found here.