Hurricane WRF (HWRF) | Development Branches

HWRF Development Branches

A Project Development Branch may be named after the user or a specific project.

To checkout a project development branch named myproject into the directory myHWRF, use the command:

svn co https://svn-dtc-hwrf.cgd.ucar.edu/branches/myproject myHWRF

Development in a subversion external

The main HWRF trunk checks out its model components from the HWRF branch of the respective repositories. The default location of the checkout will be different for developers. When one is doing development on a specific component, the external typically points to that development branch. For example, the externals list for a developer who is working on the pomtc component might look like this:

hwrf-utilities     https://svn-dtc-hwrf-utilities.cgd.ucar.edu/branches/HWRF/
ncep-coupler     https://svn-dtc-ncep-coupler.cgd.ucar.edu/branches/HWRF/
pomtc     https://svn-dtc-pomtc.cgd.ucar.edu/branches/myproject/
UPP     https://github.com/NOAA-EMC/EMC_post/branches/HWRF/
UPP/comupp/src/lib/crtm2     https://github.com/NCAR/UPP_CRTM/branches/HWRF/
WPSV3     https://github.com/wrf-model/WPS/branches/HWRF/
WRFV3     https://github.com/wrf-model/WRF/branches/HWRF/
gfdl-vortextracker     https://svn-dtc-gfdl-vortextracker.cgd.ucar.edu/branches/HWRF/

Note that the repository address for pomtc differs from the main HWRF trunk. Now the external address for pomtc points to a branch called myproject. This is called a development branch.

To make this change in your branch, use the following commands after editing sorc/.externals

• cd myHWRF/sorc
• svn propset svn:externals -F .externals .
• svn ci . -m "Updating externals to use myproject branches."

Development in a Git Repository

• Read this Wiki page. Here's the link: https://wiki.ucar.edu/display/~kavulich/SVN+to+Git+guide+for+WRF+developers
• Check out your top-level HWRF branch.
  • svn co https://svn-dtc-hwrf.cgd.ucar.edu/branches/myHWRF
• Move into the myHWRF/sorc directory. For each GitHub component that you will be developing, remove the existing directory that SVN checked out and clone them using git (checking out the HWRF branch in the process using the -b flag). Note: WRF and WPS component development for HWRF currently takes place in a special fork of the main WRF and WPS repositories.
  • WRF
    • rm -rf WRFV3
    • git clone -b HWRF https://github.com/NCAR/HWRFdev WRFV3
    • cd WRFV3
  • WPS
    • rm -rf WPSV3
    • git clone -b HWRF https://github.com/NCAR/HWPSdev WPSV3
    • cd WPSV3
  • UPP
    • rm -rf UPP
    • git clone --recursive -b HWRF https://github.com/NOAA-EMC/EMC_post UPP
    • cd UPP
  • GSI
    • ./checkoutgsi.sh (runs the git clone command for you)
    • cd ProdGSI
• git uses the "checkout" command to checkout a branch within the current repository (the one you cloned). If you add the "-b" argument, it will create a NEW branch with the name you've given. For example,
  • git checkout -b MYBRANCH --> will create a new branch called MYBRANCH and checkout that branch
  • The new branch will be created starting from whatever one you currently have checked out – that is why we checked out the HWRF branch in the previous step using the -b flag in the git clone command. In most cases, you want the starting point for your code development effort to be whatever is in the HWRF branch currently.
• Then, you can use the generic WRF-git documentation to add new or modified files to your local git repository. The command below commits your changes to your local branch in your local repository.
  • git add myfile -- whatever files you've modified
  • git commit -m "my message" -- to commit
• After you have tested a bundle of changes, you can commit these to a branch on github.com. This allows others to easily review your code.
  • git push -u origin MYBRANCH -- pushes your branch to the external repository
• Remember to update the sorc/.externals file in your myHWRF branch using the instructions above to point to your branch(es) in the component repositories.
• For more instructions on creating a new git branch:
  • Reread this wiki page: https://wiki.ucar.edu/display/~kavulich/SVN+to+Git+guide+for+WRF+developers
  • Make sure you're working from the branches/HWRF code base. Either make your branch from branches/HWRF or work in a fork on top of branches/HWRF. Recommendation: make a new branch in either scenario.
  • Once you have a clone on disk and have switched to the appropriate branch, you can run the HWRF build.

Pushing back to branches/HWRF in the main repository will follow the same procedures as any other component in a subversion repository.

SVN branch maintenance

SVN branch maintenance is critical to the successful re-integration of any new development. The following steps describe the process of using your development branch, and keeping up-to-date with other development. This will simplify the later merging of your work with others.

Create a new branch

A development branch is created at some point in time. At this point, the branch and the HWRF trunk are identical. For this example, a development branch for UPP is created, all others point to the HWRF trunk

Modify your branch with new development and commit to your branch

Do a clean check-out of your new branch, where the .externals file will point to the development branch for the component you are developing (e.g., pomtc).

svn co https://svn-dtc-hwrf.cgd.ucar.edu/branches/myproject myHWRF

Commit your new work to your own branch frequently - for example, once a day, or as blocks of work are completed. From the top-level directory of the component, i.e. sorc/pomtc/

svn commit

Update your branch with trunk updates

At the same time as you are working on your development branch, others will be adding updates to branches/HWRF. It is important to keep your branch up-to-date so that later merges will be less likely to cause errors.

Note: See this Wiki page for the Git equivalents if you are working from a Git repository component: https://wiki.ucar.edu/display/~kavulich/SVN+to+Git+guide+for+WRF+developers

Continue development

Continue with your development and testing, repeating the commit, merge and commit cycle frequently. Your development work should include frequent testing, especially following a merge/update.

HWRF Trunk Updates

Once development is complete, the code changes are pushed back onto the trunk in a two step process.

Developer tasks

DTC/External Developers Committee tasks

Notice: As of 30 June 2022, DTC has ceased all activities supporting the HWRF Developer community. The HWRF developers committee has transitioned to the UFS Hurricane Application and no longer addresses development for the HWRF system. 

• Check out a new version of your top level branch. This will automatically update the code in any component where you don't have a development branch. Note: svn update doesn't follow .externals
  From the top-level directory,

  svn co https://svn-dtc-hwrf.cgd.ucar.edu/branches/myproject myHWRF

• Manually merge the trunk for each development component (e.g., pomtc)
  

  cd myHWRF/sorc/pomtc svn merge https://svn-dtc-pomtc.cgd.ucar.edu/branches/HWRF .

• Commit the updated component to your development branch
  

  svn commit .

  • Developer completes and tests their code on their personal branch.
  • While the developer has been working a specific component, the community may also have committed changes to that component. Therefore the developer must merge any such commits into their personal branch and test again.
  • Developer presents work to the HWRF developers committee, which reviews the changes before being added to branches/HWRF of the component.
  • The developer, or at the developer’s request the DTC, merges the commits to the developer’s personal branch onto branches/HWRF of that component.
  • Once the developer’s changes have been merged onto branches/HWRF, an additional test is conducted to confirm that the “top of the branch is healthy.”
  • If the changes are to components under the HWRF core group’s control (i.e. internal), the DTC will merge these onto the respective trunk.
  • If the changes are to components not directly under the HWRF core group’s control, (such as WRF, WPS, UPP, and GSI), the DTC will interface with the respective developers committee in order integrate the changes into that component's trunk.
  • If the external developers committee rejects the developer changes, the DTC will facilitate revisions to the developer’s work so that the work is acceptable to the external developers committee.