Skip to content

GSI User Information

Jump to bottom
RussTreadon-NOAA edited this page Nov 28, 2022 · 4 revisions

Welcome to the GSI wiki! Most of the necessary information for creating branches and running the regression tests will remain on Redmine until we are able to fully work within GitHub. Please see the VLab GSI wiki for lots of good information.

There are several differences between how things were done on VLab versus GitHub. I will go over the GitHub specific changes now.

Forking the Official NOAA-EMC/GSI Repository

Only a handful of people have write access to the official repository. All development will be done through personal forks. To create a fork of NOAA-EMC/GSI, simply click the Fork button on the top right corner of the page.

Please see GitHub's help guide for forking for more information.

Cloning your Personal Fork

Now that you have created your fork, it is time to clone your fork into your workspace. The GSI still requires the libsrc and fix submodules under VLab in order to compile and run, so you will clone the fork using the --recursive option in order to fetch the contents of both the libsrc and fix submodules from VLab.

As an example, I use:

git clone --recursive [email protected]:MichaelLueken-NOAA/GSI.git

to clone my personal fork into my workspace.

Compiling the GSI on various NOAA machines

Before compiling the GSI and running regression tests, please use the following commands in your local working copy:

  1. module purge
  2. module use $PWD/modulefiles
  3. module load modulefile.ProdGSI.$machine (where $machine is the NOAA machine you are working on)

This will ensure that all modules required to compile the GSI, EnKF, and utilities are loaded before beginning the build process.

Updating your Fork when the Official Repository is Updated

You fork is a separate entity from the official repository. In order to update your fork with changes in the official repository, you will need to add a remote upstream to your local repository. To do this:

  1. Add a new upstream remote, pointing to the official NOAA-EMC/GSI repository, into your cloned fork.

    git remote add upstream https://github.com/NOAA-EMC/GSI

If you are on Luna or Surge, please use:

git remote add upstream [email protected]:NOAA-EMC/GSI.git
  1. Use git remote -v to ensure that the new upstream is properly set. Output should be similar to
[Michael.Lueken@v72a3 ush]$ git remote -v
origin  [email protected]:MichaelLueken-NOAA/GSI.git (fetch)
origin  [email protected]:MichaelLueken-NOAA/GSI.git (push)
upstream        https://github.com/NOAA-EMC/GSI (fetch)
upstream        https://github.com/NOAA-EMC/GSI (push)

  1. Use git remote update to bring in the upstream (official) repository

    git remote update

  2. If you aren't in master, then checkout master

    git checkout master

  3. Merge the upstream (official) develop to forked master

    git merge upstream/develop

  4. Ensure that your fix and libsrc submodules are updated

    git submodule update

  5. Handle potential conflicts

  6. Push updated forked master to forked repository

    git push origin master

  7. Checkout and merge updated master to personal branch

  8. Push the personal branch back to the fork.

Preparing a Pull Request (PR)

Pull requests should be prepared similar to how code was prepared for code review on VLab:

  1. Create an issue (if you haven't done so already). I will not accept changes that don't have an issue associated with them.

  2. Do a squash merge of your changes into the master of your forked repository

    git checkout master
    git merge --squash your_branch
  1. Commit and push
    git commit -m "GitHub Issue NOAA-EMC/GSI#XX.  Insert commit message here."
       where XX is your GitHub issue number
    git push origin master
  1. Please create the PR using the forked master

How to rebase the develop branch into your active PR

When changes are merged to the NOAA-EMC/GSI develop branch that overlap with changes that you have made in your PR, you will need to rebase the develop branch into your work (to correct conflicts between the authoritative repo and your fork). To do this:

  1. git remote add upstream https://github.com/NOAA-EMC/GSI.git
  2. git remote update
  3. git rebase upstream/develop
  4. Correct the conflicts that appear.
  5. git rebase --continue
  6. git commit --amend
  7. git push origin master --force

This wiki will continue to be updated as we transition fully to GitHub (and remove ourselves from VLab).

Clone this wiki locally