Contributor's Guide
Here you can find the list of steps for contributing your code, scripts, or bug fixes to the ADF diagnostics package.
If you have an troubles with any of the steps listed here then please post your problem or question to the ADF discussions page.
-
If dealing with a "bug", then please check the ADF discussions to make sure that your particular bug doesn't already have a solution (i.e. that it isn't user error).
-
Open an issue, and describe the bug or new feature you are planning to add by selecting the relevant template. Please try to add any relevant labels that might relate to your issue (e.g. "bug", "plotting", "config files"). Please note that you can add more than one label, so add as many as you think apply. Finally, 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.
-
If adding a new python script to the ADF, then it might also help to follow these instructions for linking your python script to the ADF.
1. Make a fork of the ADF 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 the ADF.
2. Clone your fork to your local system:
git clone https://github.com/<GitHub userid>/ADF
cd ADF
3. Add the NCAR repo as a remote to your locally cloned fork:
git remote add upstream https://github.com/NCAR/ADF.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/main
Please note that you may also do a git merge upstream/main 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. If applying a small change (e.g. ~10 lines), then go straight to step 4. However, if applying a large (e.g. >100 lines) modification, then 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_script.py
Where awesome_script.py 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 ADF 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>/ADF):
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. 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 "nusbaume" as a reviewer, along with anyone else who you want to review your code changes.
8. During this time automated unit tests will be run (you can see them by looking at the box above the "Merge pull request" button). If one of them should fail then you will likely get an email with a title labeled "PR run failed". For now feel free to ignore this email, as whatever the issue was will be raised during code review.
9. 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, and the unit tests will be re-run.
10. Once all unit tests pass, and all reviewers sign off on your modifications, then the PR will be merged. Congratulations! Your code is now in the ADF!
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 ADF 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.