hepo workflow (change in GOCART, part of the GEOSgcm fixture)

[pchakraborty]

Important

Most hepo commands work as follows (with clone being an exception)

hepo command [OPTIONS] [repository [repository ...]]

• If a repository is not specified, the command is executed on all repositories
• If a repository is specified, the command is executed on the specified repository and all of its upstream repositories.

Let’s consider a change in the GOCART repository, as part of the GEOSgcm fixture. The repository hierarchy looks like

GEOSgcm → GEOSgcm_GridComp → GEOSchem_GridComp → GOCART

with a registry file (.hepo/registry.yaml) in each of the 3 upstream repositories GEOSgcm, GEOgcm_GridComp and GEOSchem_GridComp. The workflow for a change in the GOCART repository would look like

Checkout some version of GEOSgcm

hepo clone -b <version> git@github.com:GEOS-ESM/GEOSgcm.git

hepo clone clones the GEOSgcm fixture and recursively clones all the sub-repos

GOCART steps

Local

(Local) Step 1: Create branch in GOCART and its upstream repositories

hepo checkout -b feature/<user>/gocart/some-change GOCART

In addition to creating this branch in GOCART and its upstream repositories, checkout also updates each of the upstream registries. For example, in GEOSchem_GridComp

GOCART:
  local: ./@GOCART
  remote: ../GOCART.git
- tag: some-old-tag
+ branch: feature/<user>/gocart/some-change
  develop: develop

Note

If we are working on multiple repositories that are not part of the same hierarchical chain, e.g. GOCART and MAPL, we will need to explicitly specify both the repositories

hepo checkout -b feature/<user>/gocart-mapl/some-change GOCART MAPL

This will create the branch feature/<user>/gocart-mapl/some-change in GOCART, MAPL and all their upstream repositories

(Local) Step 2: Modify GOCART files and commit

Commit all changes to feature/<user>/gocart/some-change in GOCART and its upstream repositories

hepo commit -m "message" GOCART

(Local) Step 3: Push all changes

Push feature/<user>/gocart/some-change from GOCART and its upstream repositories to remote

hepo push GOCART

Note

At this point all repositories should be consistent, both locally and on remote.

Remote - GitHub

(GitHub) Step 1: Pull request

Create PR for GOCART to merge feature/<user>/gocart/some-change into develop.

Note

This triggers automated testing

• Checkout fixture: hepo clone -b feature/<user>/gocart/some-change git@github.com:GEOS-ESM/GEOSgcm.git
• Build
• Run some testcase(s)

(GitHub) Step 2: Merge and issue v-tag

1. Merge feature/<user>/gocart/some-change into develop.
2. Wait for develop to be merged in to main
3. Create a new GOCART v-tag (release) that includes the new changes (e.g. v78.14.1)

GEOSchem_GridComp steps

Local

Check out tag v78.14.1 in the GOCART repository and update .hepo/registry.yaml in the upstream registries

hepo fetch
hepo checkout v78.14.1 GOCART

Caution

In case of a fresh clone, when the upstream repositories don't have feature/<user>/gocart/some-branch checked out, we need an extra step

hepo checkout feature/<user>/gocart/some-branch GEOSchem_GridComp

Commit and push

hepo commit -m "message" GEOSchem_GridComp
hepo push GEOSchem_GridComp

Remote - GitHub

(GitHub) Step 1: Pull request

Create PR for GEOSchem_GridComp to merge feature/<user>/gocart/some-change into develop.

(GitHub) Step 2: Merge and issue v-tag

1. Merge feature/<user>/gocart/some-change into develop.
2. Wait for develop to be merged in to main
3. Create a new GEOSchem_GridComp v-tag (release) that includes the new changes (e.g. v35.4.0)

GEOSgcm_GridComp steps

Local

Check out tag v35.4.0 in the GEOSchem_GridComp repository and update .hepo/registry.yaml in the upstream registries. Commit and push

hepo fetch
hepo checkout v35.4.0 GEOSchem_GridComp
hepo checkout feature/<user>/gocart/some-branch GEOSgcm_GridComp # to be safe
hepo commit -m "message" GEOSgcm_GridComp
hepo push GEOSgcm_GridComp

Remote - GitHub

(GitHub) Step 1: Pull request

Create PR for GEOSgcm_GridComp to merge feature/<user>/gocart/some-change into develop.

(GitHub) Step 2: Merge and issue v-tag

1. Merge feature/<user>/gocart/some-change into develop.
2. Wait for develop to be merged in to main
3. Create a new GEOSgcm_GridComp v-tag (release) that includes the new changes (e.g. v17.7.0)

GEOSgcm steps

Local

Check out tag v17.7.0 in the GEOSgcm_GridComp repository and update .hepo/registry.yaml in the upstream registries. Commit and push

hepo fetch
hepo checkout v17.7.0 GEOSgcm_GridComp
hepo checkout feature/<user>/gocart/some-branch GEOSgcm
hepo commit -m "message" GEOSgcm
hepo push GEOSgcm

Remote - GitHub

(GitHub) Step 1: Pull request

Create PR for GEOSgcm to merge feature/<user>/gocart/some-change into develop.

(GitHub) Step 2: Merge and issue v-tag

1. Merge feature/<user>/gocart/some-change into main.
2. Create a new GEOSgcm v-tag (release) that includes the new changes (e.g. v13.4.0)

All done!

[pchakraborty]

@tclune @mathomp4