Repository workflow

CIME uses a simplified version of the branching model described in gitworkflows(7), minus the pu (proposed updates), next and single maint branches described there.

All new features should start as a branch from master. Each feature is developed in a separate feature branch, allowing the individual features to be merged and improved independently.

Creating Issues

Before working on a new feature, or a bug fix, make sure there is an issue related to the work and assign yourself to it. Also, make sure no one is already working on the same issue.

Adding Labels

Every issue should have one or more labels from https://github.com/ESMCI/cime/labels as described below.

"may" means adding that label is optional

"must" means one label from that category must be on every issue.

Topics

topic = "tp". PR or issue. Area of CIME it concerns. An issue/PR must have one of these. Add more if the PR touches code in multiple areas of CIME.

tp: data models
tp: dead models
tp: stub models
tp: documentation - gh-pages or READMEs or other in-code docs
tp: drv mct
tp: src shr
tp: user interface (scripts in cime/scripts or ones created by create_newcase)
tp: sys test 
tp: unit test
tp: CIMElib (anything in cime/scripts/lib not part of user int or tests)
tp: script tools  (things in cime/scripts/Tools)
tp: tools  (things in cime/tools
tp: config (things in cime/config but not the model-specific dirs)
tp: unknown (issues for which you don't know the location of the bug)

Type

type = "ty". issue or PR. Must have one

ty: Bug   - issue that is a bug report
ty: Bug fix  - PR that fixes a bug.
ty: Enhancement  - use on issue that requests the Enchancement and PR that implements it)
ty: Discussion  - for issues that are just to discuss something
ty: Question - issues that ask a question

Impact

impact = "imp". PR-only. A PR may have at least one of these labels.

imp: non-BFB
imp: Climate Changing      (implies non-BFB)
imp: backwards incompat
If there is no imp label, the PR is assumed to be BFB and preserves backwards compatibility.

Status

status = "st". A closed issue may have one of these labels.

st: dup   - issue is a duplicate of a previous issue.
st: invalid - not a real issue or not one that involves CIME.
st: wontfix - a real issue but won't fix/resolve it.
Closed issues without an st label were fixed/resolved by a PR or otherwise completed.

Others

others labels without a prefix:

Critical - add to any issue or PR that needs immediate attention.
Low Priority - add to any issue or PR that does not need to be addressed soon
acme-only - add to any issue or PR for code in cime/config/acme
cesm-only - add to any issue or PR for code in cime/config/cesm

Creating Branches

Feature Branch

Start a feature branch from the most recent version of master that passed the testing. To find this version:

Go to the CIME CDash dashboard
If there are any failed (Red) results, then continually click the "Previous" button until you find a set of tests that are all Green.
In the row of a chosen machine, click on the number in the Pass column
Click on any test in the table
Find the commit in the output that looks like this:

Testing commit 421b173d8f42c926a299e5e8e0efe46e699597cb
Using cime_model = cesm

Create your branch off of this commit

Bug Fix Branches

Bug fixes should start from the earliest commit that introduced the bug: git branch username/component/bug-fix commit-with-bug.

If the bug existed before a release, start the branch as above and merge the fix to both master and, after nightly testing has passed, to the associated maint branch. At the latest, the bug-fix-branch should start from the maint release point.

Master vs. Maint Branches

To fix a bug or add a feature only in a release, start the branch from the relevant maint branch: git branch username/component/todo maint-cimeX.Y. Merge it to that maintenance branch.

Integrating a Branch with a Pull Request

When a feature is ready for testing, developers should run tests as described in Testing. Once it is considered stable, make a "Pull Request" on github to request merging the topic branch to master. Someone besides the developer must approve, and optionally perform, the merge. The new master will be tested in the nightly testing. In this model, master should be fairly stable.

Before creating the pull request, make sure the branch to be merged is up-to-date on github (i.e., make sure you have pushed the branch back to your fork). Use the New pull request button to create a pull request. There are four pull-down menus which specify the details of the merge:

base fork should be set to ESMCI/CIME
baseshould be set to master
head fork should be set to the location of your fork (e.g., <GITUSER>/cime)
compare should be set to the branch you want merged with the CIME master (i.e., your development branch)

At this point, you should see the text: "Able to merge. These branches can be automatically merged." If you see a conflict message, you must fix the conflicts in your branch. This is usually done by rebasing your branch with master.

Just below the pull-down menus, enter a subject for the pull request. The subject should be specific and describe the change being made (e.g., "Fixed <named> bug in driver", "Added new <named> feature").

Below the subject, fill in the template. Text in square brackets must be replaced with descriptive text.

When making a pull request, assign one 'Assignee' to manage the pull request. The Assignee will also review the code. Optionally, assign as 'Reviewers' everyone else you think should review the code. The Assignee should allow time for the reviewers to provide feedback and (eventually) approve the pull request. If the pull request is urgent, make that known in a comment just after creating the pull request. If a Reviewer is not available, remove them after a reasonable amount of time (which may be short for urgent PRs). When all the Reviewers have approved the PR, the Assignee can perform the merge.

Note that the Assignee is automatically considered a Reviewer and any CIME developer can add themselves as a Reviewer.