| 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.
...
- 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.
- 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.
alpha, beta, rc
Prior to a vX.0 (X >1), E3SM may add alpha, beta and rc lables to versions as follows:
...
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.
...