Dev Guide updates

.github/workflows/build_workflow.yml

@@ -2,14 +2,19 @@ name: CI/CD Build Workflow
 
 on:
   push:
+    # When a branch is pushed to GitHub, run this workflow.
+    # This will show up as the checks to pass on a pull request.
     branches: [main]
 
   pull_request:
+    # When a pull request is merged, run this workflow.
     branches: [main]
 
   workflow_dispatch:
 
+# These are the 4 jobs that show up under "All checks have passed" on GitHub.
 jobs:
+  # TODO: how does this work?
   check-jobs-to-skip:
     runs-on: ubuntu-latest
     outputs:
@@ -37,7 +42,9 @@ jobs:
 
       # Run all pre-commit hooks on all the files.
       # Getting only staged files can be tricky in case a new PR is opened
-      # since the action is run on a branch in detached head state
+      # since the action is run on a branch in detached head state.
+      # This is the equivalent of running "pre-commit run --all-files" locally.
+      # If you commit with the `--no-verify` flag, this check may fail.
       - name: Install and Run Pre-commit
         uses: pre-commit/[email protected]
 
@@ -79,6 +86,7 @@ jobs:
           conda info
           conda list
 
+      # TODO: we still do `pip install` even with everything switched to `mamba`?
       - name: Install `zppy` Package
         run: pip install .
 
@@ -87,6 +95,7 @@ jobs:
         run: |
           python -m unittest tests/test_*.py
 
+  # If the branch updates documentation, then the docs will need to be updated.
   publish-docs:
     if: ${{ github.event_name == 'push' }}
     runs-on: ubuntu-latest
@@ -121,6 +130,7 @@ jobs:
           channel-priority: strict
           auto-update-conda: true
 
+      # TODO: does this skip the publish-docs step if no docs were modified?
       - if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }}
         name: Show Conda Environment Info
         run: |
@@ -131,6 +141,7 @@ jobs:
       - name: Install `zppy` Package
         run: pip install .
 
+      # sphinx-multiversion allows for version docs.
       - name: Build Sphinx Docs
         run: |
           cd docs

.github/workflows/release_workflow.yml

@@ -1,11 +1,16 @@
 name: CI/CD Release Workflow
 
 on:
+  # This is run on release, meaning it is run when these steps are followed:
+  # https://e3sm-project.github.io/zppy/_build/html/main/dev_guide/release.html#releasing-on-github-production-releases
+  # That means this workflow is not run for release candidates.
+  # TODO: so why was it run on https://github.com/E3SM-Project/zppy/pull/429 according to https://github.com/E3SM-Project/zppy/actions/workflows/release_workflow.yml?
   release:
     types: [published]
 
 jobs:
 
+  # On a release, the docs should always be published.
   publish-docs:
     runs-on: ubuntu-latest
     defaults:
@@ -49,6 +54,7 @@ jobs:
       - name: Install `zppy` Package
         run: pip install .
 
+      # sphinx-multiversion allows for version docs.
       - name: Build Sphinx Docs
         run: |
           cd docs

docs/source/dev_guide/ci.rst

@@ -0,0 +1,24 @@
+Understanding CI
+========================
+
+In this guide, we'll cover:
+
+* Build Workflow
+* Release Workflow
+* GitHub Actions
+
+Build Workflow
+--------------
+
+The build workflow is at https://github.com/E3SM-Project/zppy/blob/main/.github/workflows/build_workflow.yml. See comments in the file for in-depth explanations of each step.
+
+Release Workflow
+----------------
+
+The release workflow is at https://github.com/E3SM-Project/zppy/blob/main/.github/workflows/release_workflow.yml. See comments in the file for in-depth	explanations of	each step.
+
+GitHub Actions
+--------------
+Both of these workflows are run by GitHub Actions. See https://github.com/E3SM-Project/zppy/actions.
+
+When a pull request is made, the build workflow is run automatically on the pushed branch. When the pull request is merged, the build workflow is once again run, but this time on the ``main`` branch.

docs/source/dev_guide/index.rst

@@ -6,9 +6,11 @@ Developer Guide
    :maxdepth: 2
 
    project-standards
+   ci
    testing
    release
-   testing_e3sm_unified
+   pre_release_testing
+   tutorial_testing_e3sm_unified
    new_diags_set
    new_glb_plot
    new_task

docs/source/dev_guide/pre_release_testing.rst

@@ -0,0 +1,26 @@
+***************************************
+Testing directions for making a release
+***************************************
+
+1. Have three shells open: one on Chrysalis, one on Compy, and one on Perlmutter. Do the following steps on each machine.
+
+2. ``cd`` to the ``zppy`` directory.
+
+3. Run ``git log``. The most recent commit should match the most recent commit on https://github.com/E3SM-Project/zppy/commits/main. This ensures that testing will use the latest code changes.
+
+4. Set up a new development environment. This ensures that testing will use the latest conda changes. Note that you will need to run ``conda remove -n zppy_dev_pre_rc<#> --all`` first if you have previously done this step. ::
+
+     mamba clean --all
+     mamba env create -f conda/dev.yml -n zppy_dev_pre_rc<#>
+     conda activate zppy_dev_pre_rc<#>
+     pip install .
+
+5. Run the unit tests with ``python -u -m unittest tests/test_*.py``.
+
+6. Run the "Commands to run before running integration tests" for the respective machine: `Chrysalis <https://github.com/E3SM-Project/zppy/blob/main/tests/integration/generated/directions_chrysalis.md>`_, `Compy <https://github.com/E3SM-Project/zppy/blob/main/tests/integration/generated/directions_compy.md>`_, `Perlmutter <https://github.com/E3SM-Project/zppy/blob/main/tests/integration/generated/directions_pm-cpu.md>`_. To ensure you don't encounter issues from running ``zppy`` commands simultaneously, wait for all the automatically launched jobs from one run to finish before running ``zppy` again.
+
+7. Run the integration tests with ``python -u -m unittest tests/integration/test_*.py``. Note that ``test_complete_run.py`` takes approximately 75 minutes to run on Compy.
+
+8. If there are any unexpected failures, fix the code before making a release, and then go back to step 1. If there are only expected failures, then update the expected files. Use the "Commands to run to replace outdated expected files" from the links on step 6. Then go back to step 7. If there are no failures at all, proceed to step 9.
+
+9. Create the release candidate by following the directions at https://e3sm-project.github.io/zppy/_build/html/main/dev_guide/release.html.

docs/source/dev_guide/release.rst

@@ -72,7 +72,7 @@ Releasing on GitHub: release candidates
 
 	$ git checkout main
 	$ git fetch upstream
-	$ git rebase upstream/main
+	$ git reset --hard upstream/main
 	$ git tag -a v1.1.0rc1 -m "v1.1.0rc1"
 	$ git push upstream v1.1.0rc1
 
@@ -92,13 +92,32 @@ Releasing on GitHub: production releases
 Releasing on conda-forge: release candidates
 --------------------------------------------
 
-1. Make a PR to `conda-forge <https://github.com/conda-forge/zppy-feedstock/>`_ from your fork of the feedstock. Note that the conda-forge bot does not work for release candidates.
+1. If you don't have a local version of the conda-forge repo, run: ::
 
-   * Start from the current dev branch and update the version number and the sha256 sum manually.
-   * Set the build number back to 0 if needed.
-   * Make the dev branch the target of the PR. Then, the package build on conda-forge will end up with the ``zppy_dev`` label.
+     git clone [email protected]:conda-forge/zppy-feedstock.git
+     git remote add upstream [email protected]:conda-forge/zppy-feedstock.git
 
-2. Check the https://anaconda.org/conda-forge/zppy page to view the newly updated package. Release candidates are assigned the ``zppy_dev`` label.
+2. If you don't have a fork of the conda-forge repo, on `conda-forge <https://github.com/conda-forge/zppy-feedstock/>`_, click the "Fork" button in the upper right hand corner. Then, on your fork, click the green "Code" button, and copy the SSH path. Run: ::
+
+     git remote add <your fork name> <SSH path for your fork>
+
+3. Get the sha256 of the tag you made in "Releasing on GitHub: release candidates": ::
+
+     curl -sL https://github.com/E3SM-Project/zppy/archive/v1.1.0rc1.tar.gz | openssl sha256
+
+4. Make changes on a local branch: ::
+
+     $ git fetch upstream dev
+     $ git checkout -b v1.1.0rc1 upstream/main # You can name the branch anything you want
+     # In `recipe/meta.yaml`, update the version and sha256 (and the build number if needed):
+     {% set version = "1.1.0rc1" %} # Set to your version
+     sha256: ... # The sha256 from the previous step
+     number: 0 # build > number should always be 0
+     $ git push <your fork name> v1.1.0rc1
+
+5. Note that the conda-forge bot does not work for release candidates. So, make a PR manually from your fork of the feedstock to the ``dev`` branch of `conda-forge <https://github.com/conda-forge/zppy-feedstock/>`_. Then, the package build on conda-forge will end up with the ``zppy_dev`` label. You can add the "automerge" label to have the PR automatically merge once CI checks pass.
+
+6. After merging, CI runs again (in a slightly different way). Then, check the https://anaconda.org/conda-forge/zppy page to view the newly updated package. Release candidates are assigned the ``zppy_dev`` label. Note that it takes about 15 minutes for the files to propagate across conda-forge's mirroring services, which must happen before you can use the files.
 
 Releasing on conda-forge: production releases
 ---------------------------------------------
@@ -119,3 +138,12 @@ Creating a New Version of the Documentation
 1. Be sure to have already completed :ref:`Releasing On GitHub <github-release>`. This triggers the CI/CD workflow that handles publishing documentation versions.
 2. Wait until the CI/CD build is successful. You can view all workflows at `All Workflows <https://github.com/E3SM-Project/zppy/actions>`_.
 3. Changes will be available on the `zppy documentation page <https://e3sm-project.github.io/zppy/>`_.
+
+Extra Resources
+---------------
+
+Conda-forge:
+
+* https://conda-forge.org/docs/user/introduction.html#why-conda-forge
+* https://conda-forge.org/docs/maintainer/infrastructure.html#admin-web-services
+* https://acme-climate.atlassian.net/wiki/spaces/IPD/pages/3616735236/Releasing+E3SM+Software+on+Anaconda+conda-forge+channel