| Table of Contents |
|---|
Background
E3SM keeps nearly all of its code in a single repository.
...
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.
Development (aka Topic or Feature) Branch Names
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.
...
Convention: E3SM branch names must 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>- Use lower-case for everything. Even your username.
- 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 E3SM IG needs one person to act as point-of-contact to answer questions about the branch and take requests for merging.
- This is why github usernames should be close to the your real name.
- Only needed for branches directly on
E3SM-Project/E3SM
- Group leads may make additional conventions for <source code area or component> and <feature-description>.
Examples
maltrud/machinefiles/mustang
...
douglasjacobsen/clm/import-v4.5.72
Permanent Branch Names: master, next, maint-x.y
What: The E3SM source code will have permanent branches used for development and maintenance of the code.
...
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.
Examples:
maint-1.0 - contains updates and bug fixes to v1.0
...
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.
...
For current and upcoming tags on master and maint-x.y see Existing and Planned Tags and Branches
Tag Names on feature branches: Archive Tags
Who: Users and teams can tag their development branches in certain cases.
...
- archive/cam/5.3.1
- archive/cam/5.3.2
- archive/cam/5.3.3
E3SM Version Names
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 E3SM adds minor new science functionality in a backwards-compatible manner, and
- PATCH version when E3SM makes backwards-compatible bug fixes that do not change answers for supported cases.
alpha, beta, rc
Prior to a vX.0 (X >1), E3SM may add alpha, beta and rc lables to versions as follows:
...
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. 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
Figure: Tags and development graph
The figure below illustrates the relationship between tag names and code development history.
...