b4b‐dev branch procedures

This page contains procedures around our b4b-dev branch. For notes from our discussions leading up to the creation of this branch, see b4b‐dev branch genesis.

Merging to b4b-dev

All code examples assume (a) your feature branch is named feature-branch, (b) your name for the CTSM repo remote is escomp, (c) you already have a PR to b4b-dev for feature-branch that has been approved.

1. If your branch is based off of master rather than b4b-dev, rebase to b4b-dev. (You could also start a new branch off b4b-dev, then cherry-pick your commits to there. Note that these are more or less the same thing, but rebasing is more automated.)
   git rebase b4b-dev feature-branch; git push
   1. If you get a message about updates being rejected because “the remote contains work that you do not have locally” or something, you will need to git push --force.
2. Ensure you have the latest version of the b4b-dev branch in your local repo:
   git checkout b4b-dev; git pull
3. Merge b4b-dev branch into your feature branch (resolving any conflicts): (reports “Already up to date.” if you don’t have anything missing from b4b-dev)
   git checkout feature-branch; git merge --no-ff b4b-dev
4. Perform testing against the latest master tag that b4b-dev is up-to-date with. (clm_short is not sufficient; do full aux_clm.)
   1. If any tests are non-bit-for-bit or fail (other than expected failures), resolve those.
   2. GOTO [1].
5. If you had to change your code in [4a] and think re-approval is necessary, get it.
6. Do git checkout b4b-dev; git pull again, to check whether someone committed to b4b-dev while your tests were going.
   1. If not up-to-date, GOTO [2].
7. Push feature-branch to its remote:
   git checkout feature-branch; git push
8. Merge the PR to b4b-dev using the Github interface.

Do not close any issues your PR resolves; instead, wait for the merge of b4b-dev to master. If your PR contains closing keywords or you’ve manually marked it as closing issues, that should happen automatically upon the next merge of b4b-dev to master.

Merging b4b-dev to master

Norms and tips

• Do not include Github user tags (e.g., @samsrabin) in merge messages, as this can result in tagged users receiving lots of notifications for things they’re not involved with.
• You can search the CTSM Github using is:pr base:b4b-dev for PRs that will be or have been merged to b4b-dev.
  • Add is:closed sort:updated-desc to get a view that lets you see what has been most recently merged to b4b-dev. (Although this can be misleading if someone adds a comment or changes labels after the merge.)
  • Or add is:open to look at open PRs only. Alternatively, look at this column of the Upcoming Tags project.

Procedure

All code examples assume your name for the CTSM repo remote is escomp.

1. Lock the b4b-dev branch on Github: Click that link, then Edit b4b-dev, then look for the word Lock.

2. Ensure you have the latest version of the b4b-dev and master branches in your local repo:
   git checkout master; git pull
git checkout b4b-dev; git pull

3. Check out a new branch from there, named as merge-b4bdev-YYYYMMDD.

   git checkout -b merge-b4bdev-YYYYMMDD

4. Merge in the latest master commit, using the tag name if the tip of master has one (which it usually should—use the hash otherwise). (If merge not needed it will be a null operation.)
   git merge --no-ff latest-master-tag-or-hash

5. Resolve any conflicts from the above. If unclear, contact author(s) of conflicting PR(s) for guidance. (git blame on the b4b-dev branch can help identify authors.)

6. ./bin/git-fleximod update

7. Perform any necessary testing—aux_clm at least, unless model code isn’t actually being touched. Compare against the latest master tag and generate baselines for the next master tag.

8. If testing shows true diffs (i.e., not just expected NLFAIL or differing field lists):

   1. Identify the responsible PR(s). (git bisect can help with this.)
   2. Contact the author(s) to see if they can suggest a quick fix. Consider your time resources and interest level; it’s your prerogative as the Dev Merger.
   3. If not, revert the responsible PR(s) back out of b4b-dev. Where abc123 is the hash of the merge commit:
      git revert -m 1 abc123
   4. GOTO [7].
   5. (PR authors: You’ll (probably?) have to submit a new PR for the branch you had merged into b4b-dev.)

9. Add entries to ChangeLog and ChangeSum.

   1. For ChangeSum description simply note “Merge b4b-dev”

10. Open a PR to merge merge-b4bdev-YYYYMMDD into master. (You may do this earlier, of course; e.g., during testing.)

11. Ensure that merging your PR will close any relevant issues.

12. Merge that PR using the Github interface.

13. Add a master tag as usual (instructions in doc/README.CHECKLIST.master_tags)

14. Merge master tag you just made back into b4b-dev.

    1. Check out your local b4b-dev.

    2. git checkout -b merge-master-YYYYMMDD

    3. git merge --no-ff latest-master-tag

    4. Open a PR to merge merge-master-YYYYMMDD into b4b-dev

       1. For PR description simply note the tag that is being merged back into b4b-dev and remove all other PR template fields.
       2. Check the box to override the PR approval requirement.

    5. Unlock the b4b-dev branch on Github: Click that link, then Edit b4b-dev, then look for the word Lock.

    6. Merge using the Github interface.

    7. Check that b4b-dev is now identical to the latest master:

       git checkout master; git pull

       git checkout b4b-dev; git pull

       git diff b4b-dev..latest-master-tag-or-hash

15. Update the "b4b-dev merge" card in Upcoming Tags (date, assignee) and move it down in the queue. (This can be done earlier, if needed.)

16. Kick off a fates test suite with the new master tag, just to generate a baseline. If anything unexpectedly fails, submit a CTSM issue.