Background
ACME keeps nearly all of its code in a single repository.
To help track development, branch and tag names in the ACME source must follow conventions given here.
For more information, see /wiki/spaces/SE/pages/3244039 page, and discussions on /wiki/spaces/SE/pages/4718815, /wiki/spaces/SE/pages/5407073, and Council /wiki/spaces/CNCL/pages/18940320.
ACME Version Names
ACME 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:
- MAJOR version when significant new science capabilities are added and old ones possibly deleted.
- MINOR version when ACME adds minor new science functionality in a backwards-compatible manner, and
- PATCH version when ACME makes backwards-compatible bug fixes.
alpha, beta, rc
Prior to a vX.0 (X >1), ACME 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.
beta = after alpha. Versions used for 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. The first rc tag is made after the coupled simulation group determines beta testing is finished AND after a code freeze. The rc versions and released versions are nearly identical.
Tag sequence before v1.0 may look like: v0.1, v0.2, .... v0.14, v0.15.....v1.0.0-alpha.11, 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
Development (aka Topic or Feature) Branch Names
What: A Development or "Topic" or "Feature" branch is made for any code changes needed for ACME. This can be new development, bug fixes, merges from CESM, or maintenance updates.
Who: Any ACME developer can create a topic branch. They can be for development or also to temporarily mark a place in the code.
Convention: ACME branch names will have the form:
<Github username>/<source code area or component>/<feature-description>
- Use lower-case for everything.
- Use hyphens instead of underscores.
- one name for the github username.
- This is the person in charge of the branch and not necessarily the only person working on it.
- The ACME SE team needs one person to act as point-of-contact to answer questions about the branch and take requests for merging.
- Task team leads can and should impose additional conventions for <source code area or component> and <feature-description>.
Examples
maltrud/machinefiles/mustang
singhbalwinder/atm/polar-mods
tangq/cam/rrm
douglasjacobsen/clm/4.5.72
Permanent Branch Names: master, next, maint-x.y
What: The ACME 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.
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".
Examples:
maint-0.0 - contains updates and bug fixes to v0.0
maint-0.1 - contains updates and bug fixes to v0.1
There is no such thing as the "maint-0.0.1" branch.
Developers should avoid using "maint" in their topic branch names.
Tag Names on master and maint-x.y
Who: Only integrators can create release tags of these branches. It is OK for users to make archival tags on master.
What: ACME will not tag every single merge into the ACME master. ACME will use tags on master to mark significant development steps, and may coincide with versions where the Coupled Model and/or Performance teams 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.
Tag Names on feature branches: Archive Tags
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
- exploratory runs were made (for climate or performance) and that commit was not already tagged on a permanent branch (see below).
- where speculative code development was performed, not merged into master, but needs to be retained
(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
- archive/cam/5.3.1
- archive/cam/5.3.2
- archive/cam/5.3.3
Tag name examples
For current and upcoming tags see Existing and Planned Tags and Branches
The figure below illustrates the relationship between tag names and code development history.
Every circle represents a commit of some code.