The purpose of this document is to provide the necessary steps for a user to issue a Pull Request (PR) to the WRF source code. A PR is the only way that new code is introduced into the WRF system. There are two types of modifications that the WRF model accepts:
- bug fixes: typically smaller and fairly limited in scope
- development: typically larger and usually associated with a new feature
Depending on the type of modification you are making (bug fixes or new development), your workflow will slightly vary. Following these instructions will help to guide you through the process to create a PR.
- If you are doing modifications for a bug-fix, you will want to base your modifications from the upcoming “release-*” branch, which uses the naming convention release-vX.X.X (e.g., release release-v4.2.1).
- If you are doing developmental work (or anything large enough that is not simply a bug fix), you will base your modifications from the “develop” branch.
The following are the sections in this document:
- Creating a Fork
- Cloning the wrf-model Fork
- Setting up Aliases for Code Updates
- Creating a Branch
- Creating a Branch for Bug Fix Modifications
- Creating a Branch for Development Work
- After Editing and Testing
- Staging Changes for a Commit
- Committing Changes
- Pushing a Branch
- Creating a Pull Request
- Accepting the Accolades
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.
You only need to "create a fork" a single time.
To begin the process of creating a PR, you must create a local copy of the WRF repository. In this step you will be obtaining the wrf-model fork from the GitHub site, and putting that entire repository on your local machine.
From a terminal window, type:
git clone https://github.com/wrf-model/WRF
This will give you a new directory called “WRF” that will contain every branch from the wrf-model remote fork. If you wish to clone this repository to a directory name other than “WRF” (which is recommended), you can use the command as follows:
git clone https://github.com/wrf-model/WRF WRF_NAME_OF_YOUR_CHOICE
For several of the processes of updating the local and the remote repositories, the user is required to fill in the remote repository URL, possibly filling in the URL quite frequently. It is convenient to have an alias set up to minimize repeatedly typing the large GitHub URL. This section walks through setting up those aliases.
Go into your local copy of the WRF repository (using the example from above, it would be cd WRF_NAME_OF_YOUT_CHOICE). When you cloned this wrf-model fork, the clone command automatically set up an alias named “origin.” The origin identifier points to the the wrf-model GitHub fork. You also want to set up an alias to your remote fork, which is later used as the location where your new modifications will be "pushed" to GitHub.
git remote add <my_fork> https://github.com/<My GitHub ID>/WRF
A user can make <my_fork> the same as their first name (for example), just to help keep track of the forks involved. The git remote add command just sets up an alias to a remote repository, it does not do anything with that repository.
You can check that the aliases "origin" and <my_fork> point to the correct locations with:
git remote -v
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 git branch command will list your working branches, with an " * " beside your current active branch.
For your work with either a bug fix or new development, you will make a new branch. When choosing your new working branch names, it is important to create descriptive and useful branch names to help remind yourself what those modifications are for. It is also important to branch off of the correct place: the most recent release branch (specifically for bug fixes) or the develop branch (specifically for new features or extensive restructuring).
Not infrequently, users find incorrect code within the WRF model. This can be nonstandard syntax in a Makefile, an initialized variable in a scheme, a missing packaged variable in the Registry, or even just wrong instructions in an example file. For these small changes, a bug fix is applied to the WRF repository. As can be seen in our [https://github.com/wrf-model/WRF/wiki/WRF-Branch-Flow](WRF Branch Flow), this bug fix will also be merged into the develop branch.
Bug fix modifications must be merged into a “release-vX.X.X” branch. An easy way for a user to determine the release branch to target is to look at the labels for the existing pull requests for the WRF model:
https://github.com/wrf-model/WRF/pulls
The labels for the top several pull requests (PRs) typically identify either a specific release branch or the develop branch where these PRs are slated. The indicated version from these release branch labels is what to select as the base branch for the modifications (and eventually where to propose the source code modifications).
-
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. You will see the appropriate release branch name (that was identified with the PR labels above); "check out" that branch:
git checkout <most_recent_release_bug_fix_branch> -
Use the following command to ensure that your copy of the release branch is up-to-date:
git pull origin <most_recent_release_bug_fix_branch> -
From the current release branch, you can now create your new branch name (again, be descriptive for you own benefit). This new branch is where you will begin making modifications:
git checkout -b <my_branch>
You want to use a different name other than "release-v4.2.1" (for example) for your local copy of the release branch name. Typically a branch name that is a short description that is associated with the modification that you are making is helpful: "PBL_divide_by_zero", "initialize_nml_for_FDDA", etc.
With the git checkout -b command, you have switched to the new branch (<my_branch>, whatever you’ve named it). You can use the git branch command to verify your current branch. At this point you are ready to make all the necessary bug-fix code modifications, and perform any necessary testing on your working branch.
More substantial modifications (such as new features, new schemes, extended capabilities, etc.) must be made from the “develop” branch. The code on this branch is subjected to more rigorous testing before release to the user community. Fundamentally, the only difference in process between a bug-fix modification and a develop modification is the selected base branch from which to cut over the user's local sandbox.
-
Checkout the develop branch:
git checkout develop
You should now be able to see the develop branch if you issuegit branch -a -
Use the following command to ensure that your develop branch is up-to-date with the wrf-model fork:
git pull origin develop -
From the current branch (develop), you can now create your new branch, and that branch is where you will begin making modifications:
git checkout -b <my_branch>
You will now automatically be on the new branch. Again, you can use the git branch command to see your current branch. At this point you are ready to make all the necessary code modifications, and perform any necessary testing to your working branch.
After the code is ready to be submitted to the WRF GitHub repository, the steps are to stage the source code to the local branch, commit those changes to the local branch, and push those changes to the GitHub repository. These steps are all performed in a terminal window on the local machine.
Once you are happy with the modifications, you will need to stage the changes:
git status -uno
This will show you all files that have been modified that are under GitHub control. If you have added a new file, GitHub will not list this file yet. The files will be highlighted in red, meaning they have not yet been staged.
git add <relative path/modified file>
You will do this for each file that you’d like to commit from the above list (including the list of new files, if you have any). Once you have added all the files, you can re-issue git status -uno and all files that will go into the commit will be highlighted in green.
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
Note that the "commit" commands requires no file names. A text window will pop up for you to describe the modifications. The WRF code has a template to follow for the structure of the commit message. A user can either include and fill in that template at this point (located in WRF/tools/commit_form.txt) or use the template that is later available on GitHub. Enter either a short one-line description or use the template from tools/commit_form.txt, and then save the file.
The next step will be to push the changes from this local branch to your remote fork of your repository: /WRF) with the alias that we set up previously:
git push -u <my_fork> <my_branch>
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 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. The code merged for a bug fix will be in the next minor release, and the new features on the develop branch will be in the next major release. You do not have to worry about accidentally merging code in the wrong location, there are enough security precautions in place to handle these situations.
-
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.
-
You might need to select "compare across forks". 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.2.1), if you are submitting a bug fix PR, or to the “develop” branch if you are submitting a PR for a new feature or enhancement.
to do a PR to the "develop" branch:
or to do a bug-fix PR, in this example to the "release-v4.2.1" branch:
-
A commit message template will automatically be in the PR text box. Fill it out appropriately if you have not already done so. At the top of the PR edit page, you will see something like:
" wants to merge 1 commit into base:develop from :<my_branch>"
Once the development committee has approved the pull request, it will be merged into the code by a member.
Please review other PRs to look at the text of their PR commit messages. You want the various parts of your message to be short enough to keep reviewers engaged, but long enough to adequately cover the topic. If a user looked at your PR, would they completely understand what you have done? For some hints and pointers, take a look at our wiki article on Making a good pull request message.