UFS Development: Branching and Contributions

Gitflow Branching Strategy

The UFS development process is inspired by the Gitflow branching strategy, which provides clear protocols for code management and development work that keep development on track, particularly in a complex forecasting system like the UFS. Within an authoritative repository, Gitflow organizes development using a series of branches with strict functions:

• develop: This is the main development branch. All code development uses this branch for syncing and coordination.
• master/main: This branch represents the mature part of the code development. It will be either released to the public or put into operations. It is updated less frequently than the develop branch and follows a strict testing protocol before it is updated.
• release: A release branch is created once develop branch code is ready to be "frozen" for (a) release to the community or (b) transition to operations. Exhaustive testing is performed on the release branch to discover and correct any bugs. Relevant changes are merged back to develop to ensure that bug fixes get back to the main development trunk.
• feature: Branches where developers work on new functionality and code enhancements (created off of the develop branch).
• bugfix: Branches that address a problem, or "bug", in the develop branch code. They are fixes to existing functionality rather than new features and are merged into develop once finished and tested.
• hotfix: Bugfix branches that provide immediate fixes to released code. These branches should be deleted after the code in them is tested and merged back to develop/master/release branches.

Generally, proposed changes to any branch are reviewed by code managers and merged after an appropriate number of reviewers have provided a favorable review and all required tests have passed.

Contributions to Development

Contributions to UFS repositories are made via a Fork and Pull Request (PR) model. GitHub provides a thorough description of this contribution model in their Contributing to a Project Quickstart, but the steps, with respect to UFS contributions, can be summarized as:

• Fork the desired repository into your personal GitHub account.

• Clone your fork onto your development system.

• Create a branch in your clone for your changes. Typically, this will be a feature, bugfix, or text (documentation-only) branch.

• Make, commit, and push changes in your clone / to your fork.

• When work is complete, create a pull request to merge your changes into the develop branch of the authoritative repository.

For future contributions, developers may delete and then recreate their fork or configure the authoritative repository as a remote repository on their clone and sync upstream changes to stay up-to-date with the official repository.

Note that these are general guidelines for UFS code management. The code management principles for specific repositories are set by the code managers for those repositories, and developers should refer directly to them.

Thank you to the Unified Workflow (UW) Development Team for their summary of the Fork and Pull Request model.