CMCC Model Changes Using Pull Requests

This page contains the standard workflow for development and/or bug fixes for CMCC-CM and its component models using Pull Requests (PRs) on GitHub.

1. Make sure there is an open issue on the model repository page that describes the need for the changes.

2. Open a Pull Request (PR)

   • Go to your fork's GitHub page, and select the "Pull requests" tab:

   

   • Create a new pull request using the "new pull request" button:

   

   • Set the "base repository" to "ESCOMP/CAM", and the "base" to your branch of interest (likely "cam_development") -- IMPORTANT NOTE -- If you believe your comparison branch is not cam_development, please contact a CAM SE to verify that this is correct:

   

   • Set the "head repository" to your CAM fork repo, and the "compare" to your newly created branch:

   

   • If the phrase "Able to merge" is present, then select "create pull request":

   

   • Add a title for your request, along with a description of what your pull request is doing. Fill out all fields in the template while removing any template comments. Be sure to list the issue(s) which are addressed by this pull request, taking care to use the correct syntax.
   • Select the appropriate labels for this PR (e.g., "bug fix", "enhancement")
   • To see the process that happens after you issue the request you may follow your issue on the ESCOMP/CAM project board.
   • If you are asked to make changes to your PR:
     • Make the requested changes on your branch
     • Re-run the test(s) you used to verify your work
     • Commit the changes to your branch
     • Push the commit(s) back to your GitHub CAM fork

3. If you are able to select a reviewer, please select the primary CAM software engineer (SE) who helped you during this process. This person will perform the preliminary review before putting it out for full code review. If there was no SE involved, do not select anyone and reviewers will be selected for you.

4. Once your PR moves up the queue and is ready for code review, you will see additional reviewers added to your PR. Please note that requests for changes show up as conversations in your PR. The person making the request will hit the "Resolve conversation" button when they are happy with your changes, so you should not close them (i.e., do not hit "Resolve conversation" unless you are the original poster in it). Instead, you can add a comment to the conversation discussing your resolution.

5. When you feel you have addressed all reviewer change requests, ask all reviewers to re-review the PR. To do this, click the "Re-request review" icon (two circular arrows) to the right of each reviewer's GitHub ID in the "Reviewers" list in the upper-right of the PR page. This notifies each reviewer to re-review the code. Repeat the last step and this step until there are no more change requests.

6. Once the changes are complete, your PR will be put in line for an upcoming CAM tag, usually the next one. When that slot opens, the primary CAM SE will run the CAM regression tests, fix any issues which may be uncovered and make final edits to the ChangeLog. At this point you have two choices on how to bring back the changes made by the CAM SE to your fork.

   1. Change permissions in your CAM fork and allow the primary CAM SE write permission to your repo. That person will then push the changes back to your fork directly. You will be able to see the changes after this has been pushed back if you want.
   2. The CAM SE will open a Pull Request to your fork with the required changes, and you will review the changes and accept them back into your fork.

7. The CAM SE will then hit the button on GitHub to bring your changes into the CAM GitHub repository.

8. Finally, if you are an NCAR Software Engineer, and need to bring in code changes to an official CAM branch yourself, then you must follow the specialized CAM SE workflow.