Getting Started for Developers - ufs-community/ufs-srweather-app GitHub Wiki

Getting started for developers

Development of the UFS Short-Range Weather (SRW) Application (App) and its components, such as the ufs-weather-model, 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 ufs-weather-model repository with SRW-relevant changes, create a fork of the ufs-weather-model and the ufs-srweather-app repositories:

   • Log in 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/ufs-weather-model)
   • Click on "fork" in the top right corner. You will see the repository in your GitHub account under "Your repositories."

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 the original 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-v2.2.0
   

   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: aqm-utils, ufs-weather-model, arl_nexus, ufs_utils, upp, 
   Checking out externals: aqm-utils, ufs_utils, upp, arl_nexus, ufs-weather-model,
   

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

    cd sorc/ufs-weather-model
    git branch -a
       * (HEAD detached at 788897d5)
         develop
         remotes/origin/HEAD -> origin/develop
         remotes/origin/develop
         remotes/origin/release/public-v3.0
    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>/ufs-weather-model
   git remote -v
      origin  https://github.com/<your_github_username>/ufs-weather-model (fetch)
      origin  https://github.com/<your_github_username>/ufs-weather-model (push)
      upstream        https://github.com/ufs-community/ufs-weather-model (fetch)
      upstream        https://github.com/ufs-community/ufs-weather-model (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-v3.0
   

   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 repository are available in the SRW App Contributor's Guide.

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