Code development with multiple repositories

Often, CAM development begins in a CAM external (e.g., PUMAS, chemistry, NCAR CCPP Atmospheric Physics). This development is a bit more complicated than working directly in CAM because multiple pull requests (and sometimes, multiple repositories) are required. There are two basic workflows for handling these situations, make a change in an external and update CAM with a new tag, and make a change both in an external and CAM. The workflow is similar for these two cases. You need the following items:

1. A branch of the external(s) in your fork of the external(s) repository
2. A branch of CAM in your fork of CAM
3. An edit to the Externals_CAM.cfg file in your CAM branch.

Making a change to a CAM external

The basic procedure for making the changes is:

1. Open a CAM issue describing the change to be made
2. Open an issue for the external (if part of that repository's workflow)
3. Set up the sandbox
4. Make needed changes to the external(s)
5. Make related changes to CAM (if needed)
6. Test changes
7. Following the workflow for the external repository, submit a PR back to the correct external branch
8. Once the external change is merged and tagged, update Externals_CAM.cfg to point to the tag
9. Run some CAM tests to make sure the changes are working
10. Open a PR back to CAM

Setting up a multi-repository sandbox

For the example below, we will make a change to the Popeye external by updating the spinach process. The ID for the GitHub fork will be YourGitID. Before you begin, make sure you have a personal fork of both CAM and the external. If the external does not use forks or is not on GitHub, modify those steps as needed. These steps will create a sandbox:

git clone -o YourGitID https://github.com/YourGitID/CAM
cd CAM
git remote add ESCOMP https://github.com/ESCOMP/CAM
git fetch --tags ESCOMP
git branch update_Popeye ESCOMP/cam_development
git checkout update_Popeye
git push -u YourGitID update_Popeye
./manage_externals/checkout_externals
cd src/physics/Popeye
git remote add YourGitID https://github.com/YourGitID/Popeye
git fetch YourGitID
git checkout -b update_spinach
git push -u YourGitID update_spinach
cd ../../..

Next, edit Externals_CAM.cfg to update the Popeye external to point to the new branch, update_spinach on your fork:

Before	After
[popeye]	[popeye]
tag = popeye_v1.2.3	branch = update_spinach
protocol = git	protocol = git
repo_url = https://github.com/ESCOMP/Popeye	repo_url = https://github.com:YourGitID/Popeye
required = True	required = True
local_path = src/physics/Popeye	local_path = src/physics/Popeye

At this point, you should be ready to continue with the workflow above.