| Table of Contents |
|---|
Background
ACME E3SM keeps nearly all of its code in a single repository.
To help track development, branch and tag names in the ACME 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.
...
E3SM Version Names
ACME E3SM will generally follow Semantic Versions 2.0.0 http://semver.org/spec/v2.0.0.html
...
- MAJOR version when significant new science capabilities are added and old ones possibly deleted.
- MINOR version when ACME E3SM adds minor new science functionality in a backwards-compatible manner, and
- PATCH version when ACME E3SM makes backwards-compatible bug fixes.
alpha, beta, rc
Prior to a vX.0 (X >1), ACME E3SM may add alpha, beta and rc lables to versions as follows:
...
What: A Development or "Topic" or "Feature" branch is made for any code changes needed for ACMEE3SM. This can be new development, bug fixes, merges from CESM, or maintenance updates.
Who: Any ACME E3SM developer can create a topic branch. They can be for development or also to temporarily mark a place in the code.
Convention: ACME E3SM branch names will have the form:
...
- 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 E3SM 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>.
...
Permanent Branch Names: master, next, maint-x.y
What: The ACME E3SM source code will have permanent branches used for development and maintenance of the code.
...
Who: Only integrators can create release tags of these branches. It is OK for users to make archival tags on master.
What: ACME E3SM will not tag every single merge into the ACME E3SM master. ACME E3SM 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.
...
- 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
- Some journals requires the precise code used in the published simulations be available publicly. Simulations made during the development process may be using code that doesn't have an official tag like "acmev1-beta01", and one can create an archive tag to identify this version. Archival tags will publicly accessible in ACME E3SM public releases.
(See /wiki/spaces/SE/pages/4718815 for discussion that articulated this use case.
...