-
Notifications
You must be signed in to change notification settings - Fork 207
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.
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.
Every issue should have on or more labels as described below.
"may" means adding that label is optional "must" means one label from that category must be on every issue.
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)
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 = "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 = "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 labels without a prefix:
Critical - add to any issue or PR that needs immediate attention.
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
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:
Using cime_model = cesm ```
- Create your branch off of this commit
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.
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.
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.
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.