Moving EAMxx development to E3SM
- Robert Jacob
Starting on November 21, 2024, all development for scream/EAMxx should be done using the main E3SM repo. You should start new branches from the E3SM master. Existing branches in your working clones can be moved to E3SM as described below.
Review the E3SM development guide Development Getting Started Guide
The main differences between E3SM development and what you might have done in SCREAM are:
feature branch name rules. Need to add “eamxx” to most branch names. Branch, Tag, and Version name conventions
Commit and PR message rules. Be precise and complete. Commit and PR message template
Don’t merge master in to your feature branch. Development Reference | DevelopmentReference AvoidRoutineMergesFromMaster
Moving a development branch
This quick guide assumes you are working with forks.
You already have a fork of scream on github and a local clone made by executing git clone from that fork. Make a fork of E3SM as well https://github.com/E3SM-Project/E3SM/
Your local clone of your scream fork probably has one remote like the following.
screamfork % git remote -v
origin git@github.com:<username>/scream.git (fetch)
origin git@github.com:<username>/scream.git (push)Add the E3SM repo fork as a second remote called “upstream” in your local clone. (Using rljacob for username)
git remote add upstream git@github.com:rljacob/E3SM.git
You now have 2 remotes
screamfork % git remote -v
origin git@github.com:rljacob/scream.git (fetch)
origin git@github.com:rljacob/scream.git (push)
upstream git@github.com:rljacob/E3SM.git (fetch)
upstream git@github.com:rljacob/E3SM.git (push)Suppose you have a branch off of the scream master that you’ve been working on.
screamfork % git branch
master
* rljacob/fix-popcornFirst, this branch name doesn’t follow the E3SM conventions. Its needs “eamxx” in it. “git branch -m” will rename the current branch.
screamfork % git branch -m rljacob/eamxx/fix-popcorn
screamfork % git branch
master
* rljacob/eamxx/fix-popcornNow just push it to the upstream
git push upstream rljacob/eamxx/fix-popcorn
You’ll see output like this:
screamfork % git push upstream rljacob/eamxx/fix-popcorn
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 300 bytes | 300.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote:
remote: Create a pull request for 'rljacob/eamxx/fix-popcorn' on GitHub by visiting:
remote: https://github.com/rljacob/E3SM/pull/new/rljacob/eamxx/fix-popcorn
remote:
To github.com:rljacob/E3SM.git
* [new branch] rljacob/eamxx/fix-popcorn -> rljacob/eamxx/fix-popcornAll the commits you’ve made to the branch will now be on the E3SM repo. You can continue development just like before. Make commits locally and push them upstream.
Do this for each scream feature branch you are working on in each clone.
Constantly remembering to use “upstream” instead of “origin” is a pain. You can completely disconnect your local clone from the scream repo by renaming the upstream remote to origin. First remove the current “origin”:
screamfork % git remote remove origin
screamfork % git remote rename upstream origin
Renaming remote references: 100% (1/1), done.
screamfork % git remote -v
origin git@github.com:rljacob/E3SM.git (fetch)
origin git@github.com:rljacob/E3SM.git (push)Or just delete your local clone and make a new one from the E3SM fork.
Moving an open issue
Its possible move an open issue from scream to E3SM if you have write permission in both.
Make sure to add the “EAMxx” label to the issue in E3SM.
Moving an open PR
Unfortunately it is not possible to move an open PR, with all its existing discussion and comments, to another repo.
Instead, move the branch (as described above) and then reopen the PR in the E3SM repo.
Make the PR description as described in Commit and PR message template
In the first comment, or below a line on the PR description, write “See previous discussion in “ and add the URL to the old scream repo PR.