Managing externals included in CIME

There are several external tools (e.g., PIO, MCT) which are included in CIME to ease its use in Earth Models. This page has some instructions for moving changes to externals into CIME and for contributing changes from CIME back to the originating external.

There are four possible workflows; Inserting in a new external into CIME as a subtree, replacing original CIME code with an external subtree, merging in changes from an external into a CIME subtree, and pulling changes from a CIME subtree to merge back to an external. Each workflow is outlined below followed by sections showing details for various workflow step types. Read the conditions at the top of each workflow to be sure to choose the correct one. Some Terminology

<external-subdir> refers to the place in the CIME tree where the external code resides (or will reside).

<external_name> is a name you give to the external so that you can refer to the external repository. Note that <external_name> can be a branch name, a commit, or a tag name.

<external_url> is the URL for the external repository.

<external_commit> refers to a branch name (<external_url>/<branch_name>), a commit, or a tag name from the external repository.

<external_branchname> refers to local branch created with git subtree split. In preparation for merging with an upstream repository.

Insert new external subtree into CIME (one-time setup)

This workflow should only be used if CIME decides to adopt code from a new external. The resulting subtree will be a new subdirectory within CIME. This will typically be done once to be followed by the 'Merge Changes' workflow below.

1. Create and switch to a branch in which to conduct the work. Be sure to follow the <?branch naming conventions> and other <?development practices>. The branch name should follow the form ??.
2. Add external git repo to as a remote in your local repository copy (git remote add -f --tags <external_name> <external_url>).
3. Add code from external git repo to CIME (git read-tree --prefix=<external_subdir>/ -u <external_commit>).
4. Commit the change (git commit).
5. Test and submit a pull request as defined in the development practices page.

Replace original (unmodified) CIME code with external subtree (one-time setup)

This workflow should only be used if original (v0.0) CIME code is being replaced with code from an external. This will typically be done once to be followed by the 'Merge Changes' workflow below.

1. Verify that the external code in the CIME repository has been not been modified since the initial commit (cd <external-subdir>; git diff --name-only v0.0 .). If there are changes (non-blank output), follow the 'Merge changes from external into CIME subtree' workflow below.
2. Create and switch to a branch in which to conduct the work. Be sure to follow the branch naming conventions and other development practices. The branch name should follow the form github-username/component/component.<version>-import.
3. Add external git repo to as a remote in your local repository copy (git remote add -f --tags <external_name> <external_url>).
4. Remove the code from your working copy (git rm -r <external-subdir>).
5. Add code from external git repo to CIME (git read-tree --prefix=<external_subdir>/ -u <external_commit>).
6. Commit the change (git commit).
7. Test and submit a pull request as defined in the development practices page.

Merge changes from external into CIME subtree (typical workflow)

This workflow may be used repeatedly anytime new work is to be moved from an external into an CIME subtree.

1. Add external git repo to as a remote in your local repository copy (git remote add -f --tags <external_name> <external_url>).
2. Create and switch to a branch in which to conduct the work. Be sure to follow the branch naming conventions and other development practices. The branch name should follow the form github-username/component/component.<version>-import.
3. Merge from external git repo to CIME (git merge --squash -X subtree=<external_subdir> --no-commit <external_commit>).
4. Commit the change (git commit).
5. Test and submit a pull request as defined in the development practices page.

Split changes from an CIME subtree for merging with an external repo

This workflow is to be used any time changes to an CIME subtree should be shared with the source external repository. For example, consider a bug fix made in the CIME MCT code. This workflow would allow contributing that fix upstream to MCT. Note that this workflow should not be used for the case where the CIME subdirectory was not brought into CIME as a subtree. That workflow is beyond the scope of this document.

Pull changes from the CIME subtree into a new branch (git subtree split -P <external_subdir> -b <external_branchname>).