Making code changes in the UFS weather model and its subcomponents

UFS-Model Code Development

Hierarchical code structure.

UFS-Weather-Model Submodules

FMS
NEMS
- NCEPLIBS-pyprodutil
fv3atm
stochastic_physics
WW3
MOM6-interface
- MOM6
CICE-interface
- CICE6
CMEPS-interface
- CMEPS

Notes

The model and its subcomponents are housed in authoritative (official) repositories. The UFS weather model uses git submodules to manage its subcomponents.
All the authoritative repositories are read-only for users.
Branches under the authoritative repositories include main develop (master) branch, production branches, and public release branches.
Branches under the authoritative repositories are protected.

Obtaining code (Using ufs-weather-model repository as an example)

Before you start:

*If you do not have a GitHub account, please get one at github.org. EMC staff can also refer to Kate Friedman’s document: “EMC GitHub Transition”:

Forking the authoritative repository

Why Choose Forking?

A fork is a copy of a repository. You manage your own fork.
Forks let you make changes to a project without affecting the original repository
You can fetch updates from the original repository
You can submit changes to the original repository with pull requests For more details, please see Working with forks

Test1
- C
- D
Test2
- A
- B
Create a fork via github:
- Login to your personal GitHub account
- Go to the official code repository website (e.g. https://github.com/ufs-community/ufs-weather-model), click on “fork” on the top right corner. You will see the repository in your own GitHub account.
Cloning your fork

git clone https://github.com/<your github username>/ufs-weather-model

Checking out the develop branch
Retrieve submodule files

Making changes & Committing

Create feature/bugfix branch

Pushing code

Forking git workflow for getting development into the authoritative repositories

The main steps involved in the forking workflow are listed below and detailed in the following sections.

Fork the relevant GitHub repositories.
- You need to make a fork for the ufs model (weather, s2s, hafs etc.) and any other component(s) where you plan to do development work, or make any change.
Clone the forked repository to your local system.
Add a Git remote for the original repository.
Create a feature branch in your fork for placing your changes.
Make your changes to the new branch.
Commit the changes to the branch.
Push the branch to GitHub (to your fork).
Update the branch with official branch in remote repository.
- During development, keep merging with develop branch in official repository
- You should "watch" the authoritative repository if you are actively working on a fork of that repo.
Open a pull request from the new branch to the original repository to propose a commit to the original repository.
After the code is reviewed and committed, clean up after your pull request is merged.

Note: In the following sections, some git commands are provided as examples to illustrate a way to use the Forking workflow. Developers may use other git commands to follow the Forking workflow.

Why Choose Forking?

A fork is a copy of a repository. You manage your own fork.
Forks let you make changes to a project without affecting the original repository
You can fetch updates from the original repository
You can submit changes to the original repository with pull requests For more details, please see Working with forks

Create a fork:

Login to your personal GitHub account
Go to the official code repository website (e.g. https://github.com/NOAA-EMC/fv3atm), click on “fork” on the top right corner. You will see the repository in your own GitHub account.

Configure remotes in cloned repository

The example below, using fv3atm, explains how to configure a remote in your fork of an original repository.

git clone https://github.com/NOAA-EMC/fv3atm  
git remote -v

You should see:

origin  https://github.com/NOAA-EMC/fv3atm (fetch)  
origin  https://github.com/NOAA-EMC/fv3atm (push)

git remote rename origin upstream  
git remote add origin https://github.com/your_github_account/fv3atm  	
git remote update  
git remote -v

Now you should see:

upstream        https://github.com/NOAA-EMC/fv3atm (fetch)  
upstream        https://github.com/NOAA-EMC/fv3atm (push)  
origin  https://github.com/your_github_account/fv3atm (fetch)  
origin  https://github.com/your_github_account/fv3atm (push)

Sync your fork

You can sync your fork with the original repository. Note: before doing this, you must configure a remote that points to the upstream repository (see previous section).

git remote -v		      (you should see upstream remote in the list)
git fetch upstream  
git checkout develop	      (this is the develop branch in your own fork)    
git merge upstream/develop    (merge the code changes from develop branch in original repo to your develop branch in your own fork)  
git push origin develop       (push to the develop branch in your own fork)

Branching

It is suggested that users create their own feature branch in their fork.
Code changes will be committed/pushed to users’ feature branch in their own fork for testing
Users’ develop/feature branch in user’s fork should be synced with authoritative (or official) repository periodically.
When development work is done, users will sync their feature branch with the latest develop/master branch in authoritative repository, run regression test and make pull request to the authoritative (or official) repository.
It is suggested to delete the feature branch in users’ personal fork after the code changes are merged into authoritative repository.
For new development work, users will sync their development with authoritative repository and start from step 1.

Create branch

Clone the authoritative repository and configure remotes as on slide 10, then create a new branch from the head of the current develop branch of the authoritative repository:

git checkout upstream/develop

The main develop branch name can differ from repo to repo, please check.

git checkout -b your_branch_name

Although it is not necessary at this point, you can push this branch to your GitHub fork:

git push origin your_branch_name

Delete branch

Locally:

git branch -d your_branch_name

Delete remote branch:

git push origin --delete your_branch_name

Another option is to go to your repository on GitHub, click on “N branches” twoards the left of panel, in the next page, select the branch and click on the trash can button on the right.

Creating and deleting branches

Merge your branch with official repository

It is critical to merge your feature branch in your fork with the develop branch in official repository. To do that, please make sure upstream remote is added to your repo (see Section Sync your fork above).

cd FV3   
git remote -v     (origin is your personal fork)  
git branch        (your_feature_branch will be shown, if not do: git checkout your_feature_branch)  
git fetch upstream  
git merge upstream/develop  
(resolve conflicts if any)  
git commit -m”sync with the official develop branch”  
git push origin your_feature_branch

Create branches for development work

UFS applications have hierarchical structure managed though git submodules. If you are making changes in UFS subcomponents, please follow these steps:

Check UFS application hierarchical structure, create your own forks from the repositories that you are going to make changes to. If you create forks in subcomponent, make sure you create forks for all the repositories in the path from the subcomponent up to ufs-weather-model.
- E.g. if you need to make changes in ccpp/physics, you need to create forks from NCAR’s ccpp/physics repository, EMC’s fv3atm repository and ufs-community’s ufs-weather-model repository
From the bottom up, create feature branches in your own forks in the code hierarchical path
Check out the ufs-weather-model recursively, create feature branches and update .gitmodules

git clone --recursive https//github.com/ufs-community/ufs-weather-model  
cd ufs-weather-model/FV3/ccpp/physics  
git checkout -b your_feature_branch

Configure remotes (slide 10): rename origin to upstream, add your fork as origin make your code changes and commit those, then push to your GitHub fork:

git push origin your_feature_branch  
cd ../../ # this is the FV3 directory   
git checkout -b your_feature_branch   
vi .gitmodules

Change url = https://github.com/NCAR/ccpp-physics to url = https://github.com/your_github_account/ccpp-physics

Change branch=master to branch=your_feature_branch

git status                               # should see .gitmodules and ccpp/physics updated  
git add .gitmodules ccpp/physics    
git commit -m “change ccpp-physics branch to your_feature_branch”
git push origin your_feature_branch  
cd ../                                   # this is the ufs-weather-model directory  
git checkout -b your_feature_branch  
vi .gitmodules

Change url = https://github.com/NOAA-EMC/fv3atm to url = https://github.com/your_github_account/fv3atm

Change branch=develop to branch=your_feature_branch

git status  (should see .gitmodules and FV3 updated)  
git commit -m ”change fv3atm branch to your_feature_branch”
git push origin your_feature_branch

Merge your branch with official repository during development

git clone  --recursive --branch your_feature_branch https//github.com/your_github_account/ufs-weather-model  
cd ufs-weather-model

For each of the modified submodules (using your own fork and branch), origin is now correctly pointing to your personal fork; thus you need to add the “upstream” remote for the authoritative repos:

git remote add upstream https://github.com/ufs-community/ufs-weather-model  
git remote update  
git remote -v show

Which shows:

origin	https://github.com/users_githubaccount/ufs-weather-model (fetch)  
origin	https://github.com/users_githubaccount/ufs-weather-model (push)  
upstream	https://github.com/ufs-community/ufs-weather-model (fetch)  
upstream	https://github.com/ufs-community/ufs-weather-model (push)

cd FV3  
git checkout your_fv3_feature_branch   
git submodule update --init --recursive

Now add upstream remote for FV3:

git remote add upstream https://github.com/noaa-emc/fv3atm  
git remote update  
git remote -v show (you should see both your fork and the noaa-emc repo as remotes)  
cd ccpp/physics  
git checkout your_ccpp_feature_branch

Now add upstream remote for ccpp:

git remote add upstream https://github.com/NCAR/ccpp-physics  
git remote update  
git remote -v show (you should see both your fork and the noaa-emc repo as remotes)

Merge with official repository, note that the upstream branch is called “master” for ccpp-physics:

git fetch upstream  
git merge upstream/master  
(resolve conflicts, if any)  
git commit -m ”merge to the latest ccpp-physics master branch”  
git push origin your_feature_branch   
cd ../../                   # now in FV3

Merge with official repository, note that the upstream branch is called “develop” for fv3atm and commit the submodule pointer update for ccpp-physics:

git fetch upstream  
git merge upstream/develop  
(resolve conflicts, if any)  
git add ccpp/physics && git commit -m “Update submodule pointer for ccpp-physics”  
git push origin your_feature_branch  
cd ../                     # now in ufs-weather-model

Merge with official repository, note that the upstream branch is called “develop” for ufs-weather-model, also commit the submodule pointer update for fv3atm and push your branch to your fork:

git fetch upstream  
git merge upstream/develop  
(resolve conflicts, if any)  
git add FV3 && git commit -m “Update submodule pointer for FV3”  
git push origin your_feature_branch

Test/use your branch with a different model

Example: test the changes in fv3atm and ccpp-physics made for the ufs-weather-model with the ufs-s2s-model
Create fork of ufs-s2s-model and clone the authoritative repository, then check out your fv3atm feature branch and update the s2s submodule pointer

git clone --recursive https://github.com/ufs-community/ufs-s2s-model  
cd ufs-s2s-model/FV3  
git remote rename origin upstream  
git remote add origin https://github.com/your_github_account/fv3atm	  
git remote update  
git remote -v  
        upstream        https://github.com/NOAA-EMC/fv3atm (fetch)  
        upstream        https://github.com/NOAA-EMC/fv3atm (push)  
        origin  https://github.com/your_github_account/fv3atm (fetch)  
        origin  https://github.com/your_github_account/fv3atm (push)  
cd FV3/ccpp/physics

Merge with official repository, note that the upstream branch is called “master” for ccpp-physics

git push origin your_feature_branch  
cd ../../                   # now in FV3

Merge with official repository, note that the upstream branch is called “develop” for fv3atm also commit the submodule pointer update for ccpp-physics

git add ccpp/physics && git commit -m “Update submodule pointer for ccpp-physics”  
git push origin your_feature_branch  
cd ../ # now in ufs-weather-model

Merge with official repository, note that the upstream branch is called “develop” for fv3atm also commit the submodule pointer update for fv3atm and push your branch to your fork.

git checkout origin/your_feature_branch  
cd ../ # now in ufs-s2s-model

Follow the steps on slides 16-17 to update .gitmodules and the fv3atm submodule pointer, create your_feature_branch in ufs-s2s-model and push to your fork.

About commit messages

Write the summary line and description of what you have done in the imperative mood
Summarize all the code changes
Always leave the second line blank.
Line break the commit message (to make the commit message readable without having to scroll

Making changes in CCPP physics 1/2

Example: change the interface (argument list) of an existing CCPP physics scheme

Follow instructions above to checkout the code, create/update branches
Make your changes to the Fortran code as usual
(example: FV3/ccpp/physics/physics/sfc_drv.f)
Add variable to metadata file for scheme (...same_path/sfc_drv.meta)

Example: change the interface (argument list) of an existing CCPP physics scheme

Scenario 1: new variable th1 exists in GFS_typedefs.F90 and has entry (i.e., standard_name and other properties in GFS_typedefs.meta) → use standard_name and other properties in sfc_drv.meta, add intent and use optional = F (don’t use optional = T, complicated!)
Scenario 2: consult with CCPP developers at EMC or DTC on new standard name, add to GFS_typedefs.meta and sfc_drv.meta as above. For more complicated scenarios see the CCPP technical documentation and consult with CCPP developers at EMC or DTC.

Testing

Developers need to fully test their branch, always sync the feature branch with the latest develop/master branch in official repository constantly
When development work is done, users need to sync their feature branch with the latest develop/master branch in official repository, run regression test
For ufs-weather-model:

cd ufs-weather-model/tests (under your feature branch)

Check the ACCNR in rt.sh, ACCNR should be a job account that developers can use to submit jobs on a platform, Please change the job account if developers can’t use the default ones.

Run the full regression test: ./rt.sh -fe

To create new baseline: ./rt.sh -ce

To run GNU compiler RT on hera:

setenv NEMS_COMPILER GNU
./rt.sh -fe -l rt_gnu.conf    # for full regression test
./rt.sh -ce -l rt_gnu.conf    # to create baseline
./rt.sh -h                    # display help

Please write down the new baseline location on the supported platforms in user’s pull request, so that the code managers can copy the baseline to the official location.

For ufs-s2s-model:

cd ufs-s2s-model

Check the ACCNR in rt.sh, ACCNR should be a job account that developers can use to submit jobs on a platform, Please change the job account if developers can’t use the default ones.

./rt.sh -ce       # create a new baseline

Please write down the new baseline location on the supported platforms in user’s pull request, so that the code managers can copy the baseline to the official location.

For ufs-hafs-model: same as for ufs-weather-model/ufs-s2s-model
Please fully test your code changes! The commit queue is crowded, if the RT fails on the supported platforms and can’t be fixed in time, the code managers have to move to next commit in order to meet the applications’ deadline.

Pull request

Pull requests (PR) tells people that your code changes from your feature branch are ready to be merged into a repository (develop branch in official repository)
An issue needs to be created associated with the pull request. The issue should cover all the features in detail.
Before making a pull request, users’ feature branch should be merged with the corresponding branch in the authoritative repository. All the conflicts should be resolved. Regression test needs to be passed on at least one of the supported platforms.
Users submit a pull request (PR) for code commit. If PRs for several repositories are cross-referenced in the description of the PR, and a note needs to be placed in each PR.
Code manager(s) will run the regression test on the required platforms that users don’t have access to.
Code managers will add reviewers.
At least one reviewer with write permission needs to give approval before the code can be committed.

Making a pull request

You need to make a pull request for each of the repository that you changed in the .gitmodule. You can start from the subcomponent repository, then make PR to each repository until the UFS application repository
To make a PR, first go to the your_github_account repository, choose your branch, then click on “new pull request”.
In the next page, choose base repository and base branch. By default, pull requests are based on the parent repository default branch.
Write down a title and some in the “write comments” description for your pull request in the “write” box. If you know the PR number of other associated repository in your commit, add them in the “write” box.
click on “Create Pull Request” button.
Making PR for other repositories in your commit. Remember to write down all the associated PRs in each of the PR. To do this, go to your PR in the official repository. In the box with title “your_github_account commented on…”, on the right, there is a button with “...”, click on it, and choose “edit”, at the end of the description, add” “associated PRs”, then list all the PRs.

Description in a pull request

Pull request size: should be small
Feature breaking: if possible, each PR is responsible for one.
Make a self-explanatory title describing what the PR does.
Description: Details with what was changed, why it was changed, and how it was changed

Code review

Reviews allow collaborators to comment on the changes proposed in pull requests, approve the changes, or request further changes before the pull request is merged.
Anyone with read access can review and comment on the changes it proposes.
Repository collaborators can assign a pull request review to any person that has been explicitly granted read access to a user-owned repository. * *
Organization members can assign a pull request review to any person or team with read access to a repository.
To assign reviewers:
- Go to the PR from repository GitHub webpage, click on “Reviewers” on the right sidebar, type in the GitHub account of the reviewer.
Review a PR
- Go to the PR from repository GitHub webpage, click on “files changed”.
- To comment the line of code, and click the blue comment icon in front of the line. To add a comment on multiple lines, click and drag to select the range of lines, then click the blue comment icon.
- In the comment field, type your comment.
Marking a file as viewed
- After you finish reviewing a file, click on “viewed” on the right of the header of the file. The file will collapse, and it will be unmarked as viewed
Submit code review
- After reviewing the files in the PR, your can submit your review.
- On the pull request, click on “Files changed”
- Above the changed code, click Review changes
- Type a comment summarizing your feedback on the proposed changes.

Commit

After the code changes are reviewed and approved by at least one code reviewer, code code can be merged.
It’s required that at least one person with write permission needs to approve the code changes before the PR can be merged.
It’s recommended that code managers also review and approve the code changes before the code is merged to the develop branch

Questions/suggestions

Please create an issue at: https://github.com/ufs-community/ufs-weather-model/issues if you have any questions/suggestions.

Making code changes in the UFS weather model and its subcomponents

UFS-Model Code Development

Hierarchical code structure.

UFS-Weather-Model Submodules

Notes

Obtaining code (Using ufs-weather-model repository as an example)

Before you start:

Forking the authoritative repository

Why Choose Forking?

Making changes & Committing

Create feature/bugfix branch

Pushing code

Forking git workflow for getting development into the authoritative repositories

Why Choose Forking?

Create a fork:

Configure remotes in cloned repository

Sync your fork

Branching

Create branch

Delete branch

Merge your branch with official repository

Create branches for development work

Merge your branch with official repository during development

Test/use your branch with a different model

About commit messages

Making changes in CCPP physics 1/2

Testing

Pull request

Making a pull request

Description in a pull request

Code review

Commit

Questions/suggestions

Home

Creating a GitHub Account for Development Work

Getting Started

Developer Information

UFS

Applications (include workflow)

Models

Utilities

Clone this wiki locally