E3SM keeps nearly all of its code in a single repository.
To help track development, branch and tag names in the E3SM source must follow conventions given here.
For background, see discussions at /wiki/spaces/SE/pages/3244039 page, /wiki/spaces/SE/pages/4718815, /wiki/spaces/SE/pages/5407073, and Council /wiki/spaces/CNCL/pages/18940320.
What: A Development or "Topic" or "Feature" branch is made for any code changes needed for E3SM. This can be new development, bug fixes, config changes or maintenance updates.
Who: Any E3SM developer can create a topic branch. They can be for development or also to temporarily mark a place in the code.
Convention: E3SM branch names on E3SM-Project/E3SM
must have the form:
<Github username>/<source code area or component>/<feature-description>
Branches on a developer's personal E3SM fork do not need to start with <Github username>
because this is clear from the fork name:
<source code area or component>/<feature-description>
E3SM-Project/E3SM
maltrud/machinefiles/mustang
singhbalwinder/atm/polar-mods
tangq/cam/rrm
douglasjacobsen/clm/import-v4.5.72
What: The E3SM source code will have permanent branches used for development and maintenance of the code.
Who: Only Integrators can change or create new permanent branches.
Convention:
master: The "trunk" or main branch of the code. Contains latest stable code. Always in a releasable state. Nearly all development should start as a branch from master.
next: A branch used for merging several topic branches for testing. Used to test several features at once. Is destroyed and re-created after the target group of features is merged to master. Also called an "Integration" branch. NEVER DO DEVELOPMENT OR SIMULATIONS FROM next.
maint-x.y: A branch started when a vX.Y release (internal or external) is made and used to provide updates and bug fixes for that release. A.k.a "release branch". After the maintenance branch is made, master can proceed to the next version.
maint-1.0 - contains updates and bug fixes to v1.0
maint-1.1 - contains updates and bug fixes to v1.1
maint-2.0 - contains updates and bug fixes to v2.0
There is no such thing as the "maint-0.0.1" branch.
Developers should avoid using "maint" in their topic branch names.
Who: Only integrators can create release tags of these branches. It is OK for users to make archival tags on master.
What: E3SM will not tag every single merge into the E3SM master. E3SM will use tags on master to mark significant development stages, and may coincide with versions where the simulations groups devote significant resources to evaluate climate or code performance.
The recommended method for users to mark specific points on the git master branch is for them to create a topic branch or fork.
For current and upcoming tags on master and maint-x.y see Existing and Planned Tags and Branches
Who: Users and teams can tag their development branches in certain cases.
What: Tags can be used to archive versions of the code. This is the case where
(See /wiki/spaces/SE/pages/4718815 for discussion that articulated this use case.
Naming:
archive/<User or Group Name>/<description>
Note that once a commit has been tagged, it will be preserved even if the branch it's on gets deleted. We recommend that unused branches be deleted and we can rely on the archive tag to keep needed commits reachable. Component teams may want to adopt a consistent versioning system within their tag namespace, such as
E3SM will generally follow Semantic Versions 2.0.0 http://semver.org/spec/v2.0.0.html
In general, versions are labeled vMAJOR.MINOR.PATCH
First release of major versions are labeled as "vX.0.0".
First release of minor versions will be labeled as "vX.Y.0" with Y>0. (Note: Y is not limited to 1-9, so we can have v1.27.0 before v2.0.0)
Bug-fixes and other changes made to a released version vX.Y will be done on a "maint-X.Y" branch and tagged "vX.Y.Z" with Z>0.
Major version zero (v0.Y) is for initial development. Anything may change at any time.
We increment the numbers as follows:
Prior to a vX.0 (X >1), E3SM may add alpha, beta and rc lables to versions as follows:
alpha = after all new features have been integrated. This version is run for a decade or more to look for instabilities not detected by short running development/integration testing. The first alpha tag is made after all the features from the feature freeze have been integrated to master. Additional alpha tags are made as needed.
beta = after alpha. Versions used for coupled tuning. The first beta tag is made after the coupled simulation group says alpha testing is finished.
rc = release candidate. Near-final version. Checked for documentation, portability. Typically, the "rc" versions and released versions are nearly identical. We don't always use "rc" tags and will go from beta to a regular release tag.
Tag sequence before v1.0 may look like: v0.1, v0.2, .... v0.14, v0.15.....v1.0.0-alpha.1, v1.0.0-alpha.2, ...., v1.0.0-beta.1, v1.0.0-beta.2, ..., v1.0.0-rc.1,v1.0.0-rc.2, ...., v1.0.0
The figure below illustrates the relationship between tag names and code development history.
Every circle represents a commit of some code.