Getting Started for Developers

Getting started for developers

Development of the UFS Short-Range Weather App and its subcomponents, such as the regional_workflow, is typically done on a user's fork. A fork is a copy of the authoritative repository and allows the user to make code changes without affecting the original repository. To set up for development work, a user will need to:

1. Create a GitHub account

2. Create fork(s) via GitHub. It is good practice to create a fork of the repository where you are doing development work, as well as any parent repository. For example, if you are modifying the regional_workflow repository, create a fork of the regional_workflow and the ufs-srweather-app repositories:

   • Login to your GitHub account
   • Go to the authoritative repository website (e.g., https://github.com/ufs-community/ufs-srweather-app or https://github.com/ufs-community/regional_workflow)
   • Click on "fork" in the top right corner. You will see the repository in your GitHub account.

3. Clone your fork of the ufs-srweather-app repository:

    git clone https://github.com/<your_github_username>/ufs-srweather-app.git

   Add the authoritative repository as a "remote" named upstream to keep track of changes made to this repository:

   git remote add upstream https://github.com/ufs-community/ufs-srweather-app.git

   Confirm your remotes:

   git remote -v
     origin	https://github.com/<your_github_username>/ufs-srweather-app.git (fetch)
     origin	https://github.com/<your_github_username>/ufs-srweather-app.git (push)
     upstream	https://github.com/ufs-community/ufs-srweather-app.git (fetch)
     upstream	https://github.com/ufs-community/ufs-srweather-app.git (push)

   Check that you are on the develop branch:

   git branch -a
     * develop
     remotes/origin/HEAD -> origin/develop
     remotes/origin/RRFS_baseline
     remotes/origin/develop
     remotes/origin/release/public-v1

   If you will be making changes in the ufs-srweather-app repository, make a new branch for your local development:

   git checkout -b feature/my_new_work
   git push origin feature/my_new_work

4. Run ./manage_externals/checkout_externals from the top directory to check out all of the submodules:

   Processing externals description file : Externals.cfg
   Checking status of externals: regional_workflow, ufs-weather-model, ufs_utils, emc_post, 
   Checking out externals: regional_workflow, ufs-weather-model, ufs_utils, emc_post,

5. After running manage_externals, a copy of the regional_workflow repository specified in Externals.cfg has been created on your local machine. To begin a new development effort, you will need to start with the latest version of the repository development branch. For the regional_workflow repository, this is the “develop” branch. From this branch, you will create a new branch, and add your development there:

    cd regional_workflow
    git branch -a
       * (HEAD detached at 5bbbc53b)
         develop
         remotes/origin/HEAD -> origin/develop
         remotes/origin/develop
         remotes/origin/release/public-v1
    git checkout develop

   Update your remotes as you did for the ufs-srweather-app. By default, “origin” is the name for the repository from which this local copy was cloned. Rename this to “upstream” and add a new remote for your own fork, for development:

   git remote rename origin upstream
   git remote add origin https://github.com/<your_github_username>/regional_workflow
   git remote -v
      origin  https://github.com/<your_github_username>/regional_workflow (fetch)
      origin  https://github.com/<your_github_username>/regional_workflow (push)
      upstream        https://github.com/NOAA-EMC/regional_workflow (fetch)
      upstream        https://github.com/NOAA-EMC/regional_workflow (push)

   Check that you are on the develop branch:

   git branch -a
       * develop
         remotes/upstream/HEAD -> upstream/develop
         remotes/upstream/develop
         remotes/upstream/release/public-v1

   Create a new branch for your local development:

   git checkout -b feature/my_new_code
   git push origin feature/my_new_code

You are ready to begin development by modifying or adding files.

Guidelines for code development in the ufs-srweather-app and regional_workflow repositories are here.

Information about code development in the UFS Weather Model is here.