Workflow for WRF Code Modification

Depending on the type of modification you are making, your workflow will vary. Following these instructions will help to guide you through the process without errors. There are 2 types of workflows: 1) bug-fix, 2) development. If you are doing modifications for a bug-fix, you will want to do this from the upcoming “release-*” branch, which uses the naming convention release-vX.0.X (e.g., release-v4.0.1). If you are doing developmental work, or anything that is not a bug fix, you will do this from the “develop” branch.

The following are the sections in this document:

Table of Contents

• Creating a Fork
• Cloning Your Fork
• Setting up Aliases for Code Updates
• Creating a Branch
  • Creating a Branch for Bug Fix Modifications
  • Creating a Branch for Development Work
• Staging Changes for a Commit
• Committing Changes
• Pushing a Branch
• Creating a Pull Request

Creating a Fork

In order to be able to make changes to the code, you will need to first go to the wrf-model/WRF GitHub home page and create your own fork from the main remote wrf-model repository. At the top right-hand corner of the page, click “Fork,” which will allow GitHub to create a copy of the original repository, and then fork it to your own account. This automatically gives you read/write/administer permissions over your personal fork. The fork will contain all branches that existed in the original repository at the time of creation.

Cloning Your Fork

To begin modifying code, you must create a local copy of the GitHub repository. In this step you will be obtaining your personal fork from the GitHub web interface and putting it on your local machine. From a terminal window, type:
git clone https://github.com/<your GitHub ID>/WRF

This will give you a new directory called “WRF” that will contain everything from your remote fork. If you wish to clone this directory to a name other than “WRF,” you can use the command as follows:
git clone https://github.com/<your GitHub ID>/WRF WRF_NAME_OF_YOUR_CHOICE

Setting up Aliases for Code Updates

Go into your local directory of WRF. When you cloned your fork, the clone command set up an alias named “origin.” Origin points to the remote repository that you cloned (<your GitHub ID/WRF). You also need to set your “upstream” to the main wrf-model repository, which is later used to ensure that your code is up-to-date:
git remote add upstream https://github.com/wrf-model/WRF

You can check that these point to the correct locations with:
git remote -v

Creating a Branch

If you have not previously made any changes in your local WRF repository, by default you are on the “master” branch. If interested, you can verify this:
git branch

This will list your working branches, with a " * " beside the branch you are currently on. When you choose your new working branch names, it is important to create descriptive and useful branch names, so that when other developers need to find related projects they can easily do so. It is also important to branch off of the correct place.

Creating a Branch for Bug Fix Modifications

Bug fix modifications must ultimately be merged into a “release-vX.0.X” branch. The development team will make the next release branch when it is determined we will need to have a bug fix release. So at the time that you are ready to make a bug fix modification, the bug fix release branch may not exist yet. You will need to determine whether there exists a current bug fix branch. For example, if the most recent official WRF release was V4.0.1, then the bug-fix branch you will need will be called "release-v4.0.2" or “release-v4.1” (dependent upon whether the next release is another bug-fix release, or a major release).

1. Use the following command to determine whether the appropriate release branch exists:
   git branch -a
   
   which will list all the available branches on the remote.
   If you see the appropriate release branch, check it out:
   git checkout <most_recent_release_bug_fix_branch>
   If not, issue the following: git pull upstream <branch_name_you_want>
   and then check again with a git branch -a. You can then check it out with git checkout <most_recent_release_bug_fix_branch>
   
   

If you are still having troubles with the above step, then you'll create your new branch from "master", and later when you create a pull request, the development team will create the bug fix branch and make sure your modifications get targeted to it. If this is the case, and you aren't currently on the "master" branch, check it out now: git checkout master

2. From the current branch, you can now create your new branch name, to which you will begin making modifications:
   git checkout -b <my_branch>

You will now automatically be on the new branch (<my_branch>, or whatever you’ve named it). Again, you can use the git branch command to see your current branch. At this point you are ready to make all the necessary bug-fix code modifications, and perform any necessary testing to your working branch.

Creating a Branch for Development Work

Developmental modifications must be made from the “develop” branch.

1. Use the following command to ensure that you have that branch, and that it's up-to-date:
   git pull upstream develop
   
   You should now be able to see the develop branch if you issue git branch -a

2. Checkout the develop branch:
   git checkout develop

3. From the current branch (develop), you can now create your new branch name, to which you will begin making modifications:
   git checkout -b <my_branch>

You will now automatically be on the new branch (<my_branch>, or whatever you’ve name it). Again, you can use the git branch command to see your current branch. At this point you are ready to make all the necessary developmental code modifications, and perform any necessary testing to your working branch.

Staging Changes for a Commit

Once you are happy with the modifications, you will need to stage the changes:
git status

This will show you all files that have been modified. The files will be highlighted in red, meaning they have not yet been staged.
git add <modified path/file name>

You will do this for each file that you’d like to commit from the above list. Once you have added all the files, you can re-issue git status and all files that will go into the commit will be highlighted in green.

Committing Changes

After staging your changes, and before pushing the changes to your remote fork, you will need to commit them to your local repository:
git commit

A text window will pop up - enter a short 1-line description of the modifications and then save the file.

#Pushing a Branch The next step will be to push the changes from your current local branch to the origin (which should be the remote fork of your repository: /WRF):
git push origin <my_branch>

#Creating a Pull Request Now that you have pushed your changes to your remote fork, you will need to go to the remote site and create a pull request (PR). This is a request to ask permission for your modifications to be merged into the main repository (either the WRF release branch, or the develop branch), that will eventually be included in the next minor/major release.

1. Go to the wrf-model/WRF GitHub home page and at the top there will be a highlighted box that asks if you want to create a new pull request. Click it to do so.

2. A commit message template will automatically be in the PR text box. Fill it out appropriately. At the top of the PR edit page, you will see something like:
   " wants to merge 1 commit into base:master from :my_branch>"
   
   Using the drop-down box, you will need to modify the "base" in that sentence to the newest release branch (e.g., base:release-v4.0.1), if you are submitting a bug fix PR (if it does not exist yet, you can leave the base as "master" for now, and the development team will create a new branch and correct the target), or to the “develop” branch if you are submitting a development PR. Once the development committee has approved the pull request, it will either be merged into the code by a member, or you will get a message that says that it’s ready to be merged. At that point, you can follow the link to the page, from your email, and click on the green "merge" button.