diff --git a/.github/workflows/build_workflow.yml b/.github/workflows/build_workflow.yml index 8b0eb936..1eab8419 100644 --- a/.github/workflows/build_workflow.yml +++ b/.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/action@v3.0.0 @@ -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 diff --git a/.github/workflows/release_workflow.yml b/.github/workflows/release_workflow.yml index f5108324..0844dbc9 100644 --- a/.github/workflows/release_workflow.yml +++ b/.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 diff --git a/docs/source/dev_guide/ci.rst b/docs/source/dev_guide/ci.rst new file mode 100644 index 00000000..4d32a5c5 --- /dev/null +++ b/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. diff --git a/docs/source/dev_guide/index.rst b/docs/source/dev_guide/index.rst index 026540c9..33117a1d 100644 --- a/docs/source/dev_guide/index.rst +++ b/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 diff --git a/docs/source/dev_guide/pre_release_testing.rst b/docs/source/dev_guide/pre_release_testing.rst new file mode 100644 index 00000000..8a965d0b --- /dev/null +++ b/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 `_, `Compy `_, `Perlmutter `_. 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. diff --git a/docs/source/dev_guide/release.rst b/docs/source/dev_guide/release.rst index b4825148..c6a45d01 100644 --- a/docs/source/dev_guide/release.rst +++ b/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 `_ 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 git@github.com:conda-forge/zppy-feedstock.git + git remote add upstream git@github.com: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 `_, 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 + +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 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 `_. 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 `. 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 `_. 3. Changes will be available on the `zppy documentation page `_. + +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 diff --git a/docs/source/dev_guide/testing_e3sm_unified.rst b/docs/source/dev_guide/tutorial_testing_e3sm_unified.rst similarity index 100% rename from docs/source/dev_guide/testing_e3sm_unified.rst rename to docs/source/dev_guide/tutorial_testing_e3sm_unified.rst