Development workflow
Here you can find the list of steps for contributing your code, scripts, or bug fixes to the atmospheric_physics CCPP repo, for eventual use in the CAM-SIMA model.
- Open an issue, and describe the bug you ran into or new feature you want added. If you are planning to commit the bug fix or feature yourself then please add yourself as the "Assignee". Otherwise just leave that field blank.
1. Make a fork of the atmospheric_physics repo.
Instructions for how to make a fork on Github in general can be found online here. Just replace the example "Spoon-Knife repo with atmospheric_physics.
2. Clone your fork to your local system, and checkout the development branch:
git clone https://github.com/<GitHub userid>/atmospheric_physics
cd atmospheric_physics
git checkout development
3. Add the NCAR repo as a remote to your locally cloned fork:
git remote add upstream https://github.com/NCAR/atmospheric_physics.git
1. Fetch the latest version of the NCAR repo:
git fetch upstream
2. Rebase your local forked branch to the NCAR version. For example, assuming you are using the main branch:
git rebase upstream/development
Please note that you may also do a git merge upstream/development if you feel more comfortable with that method.
If you then want to update your forked version on Github, then push your changes like so:
rebase:
git push -f
merge:
git push
Of course, if you run into any problems with either method then please create a discussion post that contains your message and someone will try and assist you.
1. Create a new branch:
git checkout -b cool_new_feature
where cool_new_feature is an example branch name (you can use any name you want). Next, push that new branch to your fork on Github:
git push -u origin cool_new_feature
2. Apply your code modifications and/or script additions, and perform at least one test making sure that your modifications works as expected.
3. Add all the files that you want to commit. There are multiple ways to do this, but one of the safer ways is to first check your status:
git status
This will provide a list of all modified files. For each one of those files whose modifications you want to add to the main package, you will do the following:
git add awesome_scheme.meta
Where awesome_script.meta should be replaced with whatever your file name is. Do this for each file you want to include. If you are confident that every file listed by git status needs to be added, then you can do it all at once by doing:
git add -A
You can then type git status again, at which point all of the files you added should be "staged" for commit.
4. Commit your changes to your local branch:
git commit -m "<message>"
where <message> is a short descriptor or sentence stating what the commits are for, e.g. "Fixed color bar bug" or "Added significance hatching".
5. Push your committed changes to your fork:
git push
1. Go to the NCAR atmospheric_physics repo, and click on the "Pull requests" tab.
2. There, you should see a "New pull request" button, which you should click.
3. On the new "Compare changes" page, you should see a "compare across forks" link, which you should click.
4. You should now see two new pull down boxes (to the right of an arrow). Using those pull down boxes, select your fork (which should be <username>/atmospheric_physics):
Then select the branch which contains the new commits:
5. You should then see a list of all the different modifications. If they generally look correct to you, then click the "Create pull request" button.
6. A new page should appear. In this text box add the title of your Pull request, along with text describing its purpose. If there is an associated issue, then please add the text:
Fixes #XXX
on a separate line in your text box, where #XXX is the number associated with the related issue. This can be repeated for each separate issue "fixed" by the PR. Also Please note that you also don't have to used the word Fixes, but can use any of the Github-approved keywords.
7. Add any relevant labels to the Pull request, add yourself as the assignee, and add any reviewers you would like to have. Otherwise the core SE team will add reviewers for you.
8. If you get any change requests during code review, then simply apply those changes in the same way you applied your original modifications. Please note that once you push your changes then the PR will automatically be updated.
9. Once all reviewers sign off on your modifications, then the PR will be merged. Congratulations! Your code is now in [atmospheric_physics!
10. Finally, if you have write access to the repo, then also make sure to tag your new PR merge commit following the atmospheric_physics tagging instructions.
In general all new code contributions should go into the "development" branch, with the main branch only updated (via a PR from the development branch) whenever a host model (currently just CAM or CAM-SIMA) needs a release tag.
If you are contributing something into development that needs to go into the main branch quickly please make it known in the PR description.
Before any changes can be officially accepted and merged into the atmospheric_physics main (release) branch, the branch must contain an update to the ChangeLog and NamesNotInDictionary.txt files.
1. Copy the text in doc/ChangeLog_template to the top of doc/ChangeLog
2. Fill out the new ChangeLog entry with the relevant information for your branch/PR.
Please note that some of this info won't be known until after the PR itself has been created using the steps below.
Hint: When filling out the section labeled List all existing files..., you can use the command git diff --name-status SHA, where SHA is the hash of the last official NCAR/atmospheric_physics commit.
1. Clone the CCPP standard names dictionary.
git clone https://github.com/ESCOMP/CCPPStandardNames.git
2. Run the "meta_stdname_check.py" script to generate a new "NamesNotInDictionary.txt" file.
CCPPStandardNames/tools/meta_stdname_check.py -m </path/to/atm_phys_repo> -s CCPPStandardNames/standard_names.xml > NamesNotInDictionary.txt
Where </path/to/atm_phys_repo> is a path to the head of your atmospheric_physics repo with all of the relevant changes.
3. Replace old names file with new one.
cp NamesNotInDictionary.txt </path/to/atm_phys_repo>/doc/NamesNotInDictionary.txt
Finally, once both the ChangeLog and NamesNotInDictionary.txt files have been updated, then commit and push them to your branch/fork on Github following the instructions in the section above.
Once your modifications have been merged into the official CAM repo, you may have no more use for the local fork branch created to develop those modifications. In that case, you can remove the branch both from your local cloned repo and your atmospheric_physics fork:
1. First, make sure your local repo isn't checking out the old branch, by simply checking out a different branch:
git checkout <some_other_branch>
2. Then, remove branch from local repo:
git branch -d <branch_name>
3. Finally, remove branch from personal fork repo:
git push --delete <origin> <branch_name>
You can also remove the branch via GitHub's user interface.