Documenting Release Process

CONTRIBUTING.md

@@ -45,21 +45,21 @@ In short:
 
 ## 🚀 Development Workflow
 
-Development is managed through the git repository at https://github.com/NCEAS/vegbank2.  The repository is organized into several branches, each with a specific purpose.  
+Development is managed through the git repository at https://github.com/NCEAS/vegbank2.  The repository is organized into several branches, each with a specific purpose.
 
 **main**. The `main` branch represents the stable branch that is constantly maintained with the current release.  It should generally be safe to install and use the `main` branch the same way as binary releases. The version number in all configuration files and the README on the `main` branch follows [semantic versioning](https://semver.org/) and should always be set to the current stable release, for example `2.8.5`.
 
 **develop**. Development takes place on a single branch for integrated development and testing of the set of features
 targeting the next release. Commits should only be pushed to this branch once they are ready to be deployed to
 production immediately after being pushed. This keeps the `develop` branch in a state of readiness for the next release.
-Any unreleased code changes on the `develop` branch represent changes that have been tested and staged for the next 
-release. 
+Any unreleased code changes on the `develop` branch represent changes that have been tested and staged for the next
+release.
 The tip of the `develop` branch always represents the set of features that are awaiting the next release. The develop
 branch represents the opportunity to integrate changes from multiple features for integrated testing before release.
 
 Version numbers on the `develop` branch represent either the planned next release number (e.g., `2.9.0`), or the planned next release number with a `beta` designator or release candidate `rc` designator appended as appropriate.  For example, `2.8.6-beta1` or `2.9.0-rc1`.
 
-**feature**. To isolate development on a specific set of capabilities, especially if it may be disruptive to other 
+**feature**. To isolate development on a specific set of capabilities, especially if it may be disruptive to other
 developers working on the `develop` branch, feature branches should be created.
 
 Feature branches are named as `feature-` + `{issue}` +  `-{short-description}`, with `{issue}` being the GitHub issue number related to that new feature. e.g. `feature-23-refactor-storage`.
@@ -73,11 +73,11 @@ been tested and are awaiting release.  Thus, each `feature-*` branch can be test
 ### Development flow overview
 
 ```mermaid
-%%{init: {  'theme': 'base', 
+%%{init: {  'theme': 'base',
             'gitGraph': {
                 'rotateCommitLabel': false,
                 'showCommitLabel': false
-            },            
+            },
             'themeVariables': {
               'commitLabelColor': '#ffffffff',
               'commitLabelBackground': '#000000'
@@ -106,16 +106,21 @@ gitGraph
 
 ## 🔀 Release process
 
+> [!IMPORTANT]
+> Use the detailed [Release Checklist Template](./release-checklist.md) to create a GH `task` Issue for each release.
+
+In general, the release process follows these steps:
+
 1. Our release process starts with integration testing in a `develop` branch. Once all
 changes that are desired in a release are merged into the `develop` branch, we run
 the full set of tests on a clean checkout of the `develop` branch.
-2. After testing, the `develop` branch is merged to main, and the `main` branch is tagged with
-the new version number (e.g. `2.11.2`). At this point, the tip of the `main` branch will 
-reflect the new release and the `develop` branch can be fast-forwarded to sync with `main` to 
-start work on the next release.
-3. The release is tagged on GitHub, and the metadata for the reserved DOI is added and published with the correct softwareheritage url. Finally, the release is added to the GitHub `Releases` page
-4. The new release is then built and published as a Docker image (see the [Docker README for details](./docker/README.md)), and the Helm chart is packaged and published to the GitHub Container Registry (see the [Helm README](./helm/README.md#packaging-and-publishing-the-helm-chart)). The Helm chart release should also be tagged, using the chart version (which may differ from the application code version) with a `chart-` prefix. For example, if the application code version is `2.0.1` and the chart version is `1.0.1`, then the chart should be tagged with `chart-1.0.1`.
-5. An email announcement is sent out to users and contributors.
+2. After testing is completed, and version numbers and DOI/citation have been updated, the `develop` branch is then merged to main.
+3. From `main`, the new release is then built and published as a Docker image (see the [Docker README for details](./docker/README.md)), and the Helm chart is packaged and published to the GitHub Container Registry (see the [Helm README](./helm/README.md#packaging-and-publishing-the-helm-chart)). The helm chart should then be deployed on the dev cluster, to make sure it works as expected.
+4. Then the `main` branch is tagged with:
+   1. the new version number (e.g. `2.0.1`) and
+   2. the Helm chart version (which may differ from the application code version) with a `chart-` prefix.
+   For example, if the application code version is `2.0.1` and the chart version is `1.0.1`, then the chart should be tagged with `chart-1.0.1`.
+5. Finally, the app and chart releases are added to GH `Releases` page and announced as appropriate to users and contributors
 6. Availability:
    - Releases can be downloaded from the [GitHub releases page](https://github.com/NCEAS/vegbank2/releases).
    - Versioned Docker images are available from [the VegBank GHCR image repo](https://github.com/NCEAS/vegbank2/pkgs/container/vegbank), and can be downloaded using:

README.md

@@ -76,25 +76,41 @@ commits can be run, for example, for the Mac with:
 
 ### Installing `vegbank` locally
 
-We are using `uv` as our python environment and dependency manager. To get started locally, follow these instructions below:
+We are using `uv` as our python environment and dependency manager. To get started locally:
 
-```sh
-# Step 1: Set your `VIRTUAL_ENV` path (if not already set)
-$ export VIRTUAL_ENV=/data/venv
+#### One-time setup
 
-# Step 2: Install `uv` (if not already installed)
-$ python -m pip install uv --root-user-action ignore
+1. Provision a local database - see [database/INSTALL.md](./database/INSTALL.md) for instructions on setting up a local postgres instance with the vegbank database and user.
+2. Set the following environment variables in the shell where you will start the application. You can do this manually, or in your `.bashrc` or `.zshrc` file, etc:
+   - `VB_DB_NAME`: database name (typically `vegbank`)
+   - `VB_DB_USER`: the user that owns the db (typically also `vegbank`)
+   - `VB_DB_PORT`: your psql port (typically `5432`)
+   - `VB_DB_PASS`: password for your db user
+   - `VB_ACCESS_MODE`: access mode. Set to `open` (or "read_only", if you don't need to do uploads)
+   (`VB_DB_HOST` is not needed for local development)
+3. Install `uv` (if not already installed)
 
-# Step 3: Navigate to your project root
+   ```shell
+   $ python -m pip install uv --root-user-action ignore
+   ```
+
+#### Update and Run the Application
+
+```shell
+# Navigate to your project root
 $ cd /path/to/vegbank2
 
-# Step 4: Create/reuse the venv and activate it
-$ uv venv --allow-existing ${VIRTUAL_ENV}
-$ source ${VIRTUAL_ENV}/bin/activate
+# Create a project-local virtual environment
+$ uv venv .venv
+
+# Activate the virtual environment
+$ source .venv/bin/activate
 
-# Step 5: Install all dependencies into the venv
+# Install project dependencies
 $ uv sync --active
 
+# Run the application
+uv run flask --app src/vegbank/app.py run
 ```
 
 ### Adding project dependencies
@@ -107,9 +123,6 @@ To add a dependency to this project, you will need to update `pyproject.toml` wi
 
 ```py
 # pyproject.toml
-
-...
-
 dependencies = [
     "psycopg>=3.3.2",
     "flask>=3.1.2",
@@ -141,7 +154,7 @@ The vegbank Helm chart can be used to deploy the `vegbank` service on a Kubernet
 
 ## Release Process
 
-See the [Contributing Guide](./CONTRIBUTING.md) for details on the release process
+See the [Release Checklist](./release-checklist.md) and the [Contributing Guide](./CONTRIBUTING.md#-release-process) for details on the release process
 
 ## Current Contributors
 
@@ -185,7 +198,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ```
 
-## Acknowledegments
+## Acknowledgments
 
 Work on this package was supported by:
 

release-checklist.md

@@ -0,0 +1,33 @@
+# Vegbank Release Checklist Template
+
+When testing is complete on the develop branch, create a new issue containing the following checklist. Then, follow the steps to prepare and publish the release.
+
+- [ ] Create a branch named `task-<this-issue-#>-<version-tag>-release-prep`, and push the following changes:
+  - [ ] **pyproject.toml & uv.lock**: Update the VegBank version number in `pyproject.toml`, and [install dependencies using uv](README.md#installing-vegbank-locally), in order to update the `uv.lock` file (since this also contains the vegbank version number). Commit both.
+  - [ ] **Chart.yaml**: Update chart `version` and `appVersion`
+  - _(IGNORE FOR PATCH RELEASES)_: `README.md`:
+    - [ ] Update release number
+    - [ ] Add new DOI and citation for this release
+  - [ ] PR & merge release prep branch to `develop`
+- [ ] PR & merge `develop` -> `main`
+- [ ] [Build and push docker image](./docker/README.md#step-3-build--push-your-image)
+- [ ] [Package and push helm chart](./helm/README.md#packaging-and-publishing-the-helm-chart)
+- [ ] install the new helm chart in dev, and confirm it works as expected
+- [ ] Tag the release:
+
+    ```shell
+      # get the git sha
+      git rev-parse --short HEAD
+
+      # tag the api code release
+      git tag x.x.x <commit-sha>
+
+      # tag the helm chart release
+      git tag chart-x.x.x <commit-sha>
+
+      # IMPORTANT - DON'T FORGET THIS!
+      git push --tags
+    ```
+
+- _(IGNORE FOR PATCH RELEASES)_: Add the metadata for the reserved DOI and publish it with the correct softwareheritage url
+- [ ] Add to GH `Releases` page and announce as appropriate