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.

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.

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.

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

1. Go to the CIME CDash dashboard

2. If there are any failed (Red) results, then continually click the "Previous" button until you find a set of tests that are all Green.

3. In the row of a chosen machine, click on the number in the Pass column

4. Click on any test in the table

5. Find the commit in the output that looks like this:

Testing commit 421b173d8f42c926a299e5e8e0efe46e699597cb Using cime_model = cesm ```

6. Create your branch off of this commit

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.

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 making a pull request, assign as 'Reviewers' everyone you think should review the code. Assign an 'Assignee' to manage the pull request. 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.