Moving EAMxx development to E3SM

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.

1 Moving a development branch
2 Moving an open issue
3 Moving an open PR

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-popcorn

First, this branch name doesn’t follow the E3SM conventions. Its needs “eamxx” in it. “git branch -m” will rename the current branch.

Now just push it to the upstream

git push upstream rljacob/eamxx/fix-popcorn

You’ll see output like this:

All 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”:

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.

See https://docs.github.com/en/issues/tracking-your-work-with-issues/administering-issues/transferring-an-issue-to-another-repository#transferring-an-open-issue-to-another-repository

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.