Repository

Branching Policy

ESMF uses a branching policy adapted from GitFlow. There are two permanent branches, main and develop as well as branches for feature development and releases. The branching strategy allows developers to continue committing to an integration branch (develop) even while a release is in process. It supports patching previous releases. Finally, it support a branch (main) which offers a high degree of stability.

Description of branches:

• develop is the main integration branch and undergoes nightly testing. Developers working on new features or fixes should merge changes into develop regularly to ensure timely integration and testing of code. Features need not be complete to merge into develop but should come in logical chunks. (Note: Releases should not contain partial features that are public facing, so merges into develop should in general not introduce a partial feature with a public API.) Regular "beta snapshot" tags are placed on develop as reference points.

• main is the stable branch and contains tags for major and minor releases of ESMF. Developers are not committing or merging to main for day-to-day development. Instead, main is updated by merging from a release branch during a release process. main does not contain patch release tags since those tags must be applied to a release branch.

• Feature branches (prefixed with: feature/, e.g., feature/update_io) are where development occurs for new features. In most cases feature branches are branched from the develop branch to stay up to date with the most recent integrated code. Feature branches are merged back into develop when branch testing indicates that the feature is ready for integration testing, or a logical subset of the feature is ready for integration testing.

• Release branches (prefixed with: release/ e.g., release/8.1) are created at the start of a release cycle. The release branch branches off from develop. Heavy testing occurs on the release branch and only fixes that result from release testing are committed to the branch. These fixes are also merged back to develop so they are not lost (either immediately or post-release). When the release is ready, the release branch is merged into main and then main is tagged. The release branch is also merged back into develop. Release branches are retained to support patches.

• Patches to previous releases are handled by checking out the release branch in question and committing the fix to the release branch. The patched release must be tagged on the release branch itself since in most cases the main branch will have moved on.