Update documentation

Author: github-actions[bot]

main/.doctrees/environment.pickle

@@ -11,7 +11,15 @@ E3SM-developed dependencies.
 
 ## Step-by-Step: Creating an RC for `e3sm_diags`
 
-### 1. Tag a Release Candidate in the Source Repo
+### 1. Tag a Release Candidate or Make a GitHub Release
+
+#### 1.1 Tag a Release Candidate in the Source Repo
+
+In some repos like MPAS-Analysis, it is desirable to tag a release candidate
+without making a GitHub release page.  This avoids clutter and confusion.
+
+We will use E3SM Diags in this example even though this is not the preferred
+workflow for that repository.
 
 Go to the source repository:
 [E3SM Diags GitHub](https://github.com/E3SM-Project/e3sm_diags)
@@ -36,6 +44,57 @@ git push origin v3.0.0rc1
 
 ---
 
+#### 1.2 Perform at GitHub Release
+
+In other repositories like E3SM Diags and zppy, developers prefer that you
+create release pages for release candidates.  These pages provide clarity and
+provenance for the release candidate just like for a normal release.
+
+Follow these steps to create a release candidate via GitHub:
+
+- **Pull the latest changes on `main`:**
+  ```bash
+  git checkout main
+  git pull origin main
+  ```
+
+- **Create a new branch from `main`:**
+  ```bash
+  git checkout -b bump/0.1.0rc1
+  ```
+
+- **Push the branch to your fork or upstream:**
+  ```bash
+  git push --set-upstream origin bump/0.1.0rc1
+  ```
+
+- **Bump the version in the Python files:**
+  - You can use the `tbump` tool (available in the conda development
+    environments for `e3sm_diags` and `e3sm_to_cmip`):
+    ```bash
+    tbump 0.1.0rc1 --no-tag
+    ```
+    This will automatically update version strings, add, commit, and push
+    changes to remote.
+  - Alternatively, manually update version strings in files such as
+    `pyproject.toml`, `setup.py`, and `<python_package>/__init__.py`. Then
+    add, commit, and push these changes.
+
+- **Open a pull request:**
+  - Use your `bump/0.1.0rc1` branch as the source and merge into `main`.
+  - Example: [Compare · E3SM-Project/e3sm_to_cmip](https://github.com/E3SM-Project/e3sm_to_cmip/compare)
+
+- **Publish a new GitHub Release:**
+  - Go to the [GitHub Releases page](https://github.com/E3SM-Project/e3sm_to_cmip/releases/new).
+  - Click "Choose a tag" and enter `0.1.0rc1` (ideally without a `v`, but
+    follow the repo’s conventions).
+  - For "Release title", use `v0.1.0rc1` (with a `v`).
+  - Click "Generate release notes" and organize the changelog as needed.
+  - Check the box "Set as a pre-release".
+  - Click "Publish release".
+
+---
+
 ### 2. Prepare the Feedstock PR
 
 Go to the conda-forge feedstock for `e3sm_diags`:
@@ -117,7 +176,7 @@ conda install -c conda-forge/label/e3sm_diags_dev e3sm_diags
 
 Creating an RC for a dependency involves:
 
-1. Tagging the source repository
+1. Tagging a Release Candidate or making a GitHub release
 2. Opening a PR on the feedstock targeting the `dev` branch
 3. Waiting for CI to pass, then merging
 

main/.doctrees/releasing/creating-rcs/rc-dependencies.doctree

@@ -35,63 +35,30 @@ Edit `recipes/e3sm-unified/meta.yaml`:
   `e3sm_diags`, `mpas-analysis`, etc.)
 
 ---
+## 3. Run `build_packages.py`
 
-## 3. Regenerate the Build Matrix
+If you are building packages for an RC version of E3SM-Unified, the script
+will build packages for Python 3.10 and the `nompi` and `hpc` versions of MPI
+by default (those needed for login and compute nodes, respectively, on HPC).
+You may wish to use the `--python` and `--mpi` flags to override these.
 
-Run the matrix generator script to define combinations of Python and MPI:
+You should supply the `--conda` flag if not using `~/miniforge3`.
 
 ```bash
-cd recipes/e3sm-unified/configs
-rm *.yaml
-python generate.py
+./build_packages.py --conda ~/minforge3 --python 3.10 --mpi nompi hpc
 ```
 
-This produces matrix files like:
+The script will produce a matrix of files like:
 
-* `mpi_mpich_python3.10.yaml`
-* `mpi_hpc_python3.10.yaml`
+* `configs/mpi_nompi_python3.10.yaml`
+* `configs/mpi_hpc_python3.10.yaml`
 
----
-
-## 4. Edit `build_package.bash`
-
-Update the channel list to include dev labels for any packages still in RC
-form. For example:
-
-```bash
-channels="-c conda-forge/label/chemdyg_dev \
-         -c conda-forge/label/e3sm_diags_dev \
-         -c conda-forge/label/mache_dev \
-         -c conda-forge/label/mpas_analysis_dev \
-         -c conda-forge/label/zppy_dev \
-         -c conda-forge/label/zstash_dev \
-         -c conda-forge"
-```
-
-Then define which matrix files to test. For example:
-
-```bash
-for file in configs/mpi_mpich_python3.10.yaml configs/mpi_hpc_python3.10.yaml
-do
-  conda build -m $file --override-channels $channels .
-done
-```
-
-Make sure:
-
-* You use `--override-channels` to isolate testing to dev packages
-* You only include dev labels for packages with RCs — use stable versions
-  otherwise
+These are then used by `conda build` to build the appropriate variant of
+the conda package.
 
 ---
 
-## 5. Build and Troubleshoot
-
-Run the script:
-
-```bash
-bash build_package.bash
-```
+## 4. Troubleshoot
 
 If builds fail, consult the
 [Troubleshooting Conda Build Failures](rc-troubleshooting.md) guide.
@@ -100,7 +67,7 @@ resolution issues.
 
 ---
 
-## 6. Make a draft PR
+## 5. Make a draft PR
 
 Push the branch to your fork of `e3sm-unified` and make a draft PR to the
 main `e3sm-unified` repo.  Use that PR to document progress and highlight
@@ -110,7 +77,7 @@ acces to E3SM's Confluence pages). See
 
 ---
 
-## 7. Keeping updated on Confluence
+## 6. Keeping updated on Confluence
 
 As deployment and testing progresses, you needs to make sure that the packages
 in your `update-to-<version>` branch match the
@@ -127,7 +94,7 @@ jargon**) what is new in their package that would be of interest to users.
 
 ---
 
-## 8. Tag and Publish the RC
+## 7. Tag and Publish the RC
 
 After test builds are successful:
 

main/.doctrees/releasing/creating-rcs/rc-e3sm-unified.doctree

@@ -73,6 +73,25 @@ using the [Creating Release Candidates](creating-rcs/overview.md) workflow.
 
 ---
 
+## ✍️ Updating `meta.yaml`
+
+Once the package list and versions are finalized, update the
+[`recipes/e3sm-unified/meta.yaml`](https://github.com/E3SM-Project/e3sm-unified/blob/main/recipes/e3sm-unified/meta.yaml)
+file to reflect the new selections. This file is the authoritative source for
+the conda environment and must be kept in sync with the planned versions.
+
+- Edit the `meta.yaml` to add new packages, update versions, or remove
+  deprecated packages as needed.
+- Ensure that all changes are consistent with the decisions made during
+  planning.
+- Commit these changes to your release branch as part of preparing the
+  release candidate.
+
+> **Tip:** Also update `e3sm_supported_machines/default.cfg` to match, unless
+  there is a technical reason to diverge.
+
+---
+
 ## 📦 Managing Version Pins During Conda-Forge Migrations
 
 E3SM-Unified often needs to coordinate with conda-forge's centralized version