Developing on a Feature Branch (WIP)

Create a Feature Branch

Creating a feature branch is very simple, however, there are some settings that have to be changed in order for anyone other than a gatekeeper to land changes to it. Generally, only gatekeepers should land changes, however, for feature branches it becomes too cumbersome when a feature branch needs to be merged with master. There is less impact and risk with landing to a feature branch so in addition to gatekeepers, the lead feature developers can also land to a feature branch.

Create the branch and push to GitHub. (This is assuming the repository remotes are setup already)

git checkout master
git checkout -b feature/[feature branch name]
git push -u origin feature/[feautre branch name]

Request an administrator on the GitHub repository to add the lead feature branch developer to the list of people that has push access to the feature branch. This is because all branches under the “feature/” namespace will have extra restrictions applied to them. The lead developer needs to be able to land PRs to it, and also to merge and push directly, like any other development branch. This latter permission is needed in order to merge master into the feature branch.

Merge with Master

It’s generally advantageous to keep the feature branch up to date with master. There are a two main approaches that can be taken: merging and rebasing. Since a feature branch is typically shared among multiple developers, merging is the best approach to avoid destroying the shared history.

The merge should be performed by a developer with direct push access to the branch.

git checkout [feature_branch]
git fetch origin
git merge origin/master
# Resolve conflicts if needed
git submodule update
git add [conflict files]
git commit
git push

If there are significant conflicts that need to be resolved, it might be a good idea to have the changes code reviewed. It’s also a good idea to build and test locally before pushing the merge.

It is not good to use a PR for this process. The default landing option for our git repo is squash-and-merge, which will create a new commit made of all the others. This would create conflicts when the branch is landed to master.

Landing to the Feature Branch

Landing to the feature branch is very similar to landing to master. The key difference is GitHub doesn’t automatically select the feature branch as the target branch when creating a Pull Request. It is still expected that changes that land to a feature branch have at least 2 reviewers approve the changes.

Ideally, a gatekeeper will land changes to a feature branch, however, if a change has appropriate approvals and acceptable CI passing, then a lead feature developer can land.

It is ideal to have all tests passing. However, in practice, there may be issues in master. To avoid re-running CI for non-PR-related issues, or issues intended to be resolved in another PR in feature development, the feature branch may have all GitHub checks set to “not required” – I.e. the PR can be landed by a lead feature developer, even if there are test failures. However, the failures should still be inspected to verify the cause before landing, and tickets created against the branch if needed. This is all done on the honor system, so all branch developers should agree upon the requirements in advance.

CI and Feature Branches

To run the feature branch through CI, create a draft PR for the branch with master as the destination branch. This PR isn’t actually intended to land (at least not yet), it’s purpose is to initiate CI on the branch. Then, anytime changes land to the feature branch (including merging with master) it should start a new CI build and test process.

Feature Branch Exit Criteria

The following criteria must be met before considering landing the feature branch into master

Requirements are defined in SRS Jira Project
Design document is complete, reviewed, and approved utilizing the team template
Test plan for feature is complete, reviewed, and approved utilizing the team template.
Planned software feature is 100% implemented with “required for version”
Test automation and CI is 100% complete with “required for version”
No defects with high/critical exposure or “required for version”
No new daily or weekly regression test failures (failures not already on master branch)
All tests are passing for feature in weekly and daily regression tests
All user documentation updated and reviewed (e.g., admin guide, user guide)
Performance and scale testing executed according to test plan/required requirements. Results are reviewed and approved
SDL Code scans are competed (Coverity, Bandit, Checkmarx, Snyk). For all scans, all issues have been dispositioned, and the issues that are required per SDL rules have been fixed.
Any new dependencies identified and Oked
Does not regress endurance testing from current master baseline with feature enabled
Does not regress scale testing from current master baseline with feature enabled
Code coverage results have been reviewed to identify gaps in testing, and test plan has been updated and executed accordingly. Functional and branch coverage each are equivalent or better than master
Manual test plans and “out-of-box experience” testing are 100% executed with “required for version”. Manual test results are recorded
Usability is evaluated and results are reviewed

Landing Feature Branch to Master

The process for landing a feature branch into master - TBD