Skip to content

Code development with multiple repositories

Jump to bottom
cacraigucar edited this page Oct 16, 2024 · 9 revisions

Contents

Introduction

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
bin/git-fleximod update
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.

Updating your sandbox when an external has been updated

When an external you are working on has been updated, you will need to merge these changes into your branch. For the steps below, we will again assume you have your sandbox set up as above and will be updating your branch of the Popeye external. Someone has just updated project Popeye with the new tag, popeye_v2.1.3. Follow these steps:

  • First, make sure your branch has no modifications 
    cd src/physics/Popeye
git status
    • If your branch shows any modifications, commit them before proceeding. Pushing your commits to your fork is also advised.
  • Fetch the new tag from the main Popeye repository and merge into your branch: 
    git fetch --tags origin
git merge popeye_v2.1.3
    (note a rebase will work as well as a merge in this situation).

Finally, note that similar steps will enable you to merge in updates from the main repository. Make sure you are at the top level of your CAM repository and that your sandbox is clean (i.e., using git status). Then (to merge in the latest from the development branch):

git fetch ESCOMP
git merge ESCOMP/development

CAM wiki

CAM Documentation

CAM Model Development

Clone this wiki locally