From 2eb98d72ef402660f3aed52bef42531bae023b6a Mon Sep 17 00:00:00 2001 From: Matthew B <106352182+artntek@users.noreply.github.com> Date: Wed, 1 Apr 2026 10:25:19 -0700 Subject: [PATCH 1/5] template for release checklist --- release-checklist.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 release-checklist.md diff --git a/release-checklist.md b/release-checklist.md new file mode 100644 index 0000000..0b07fad --- /dev/null +++ b/release-checklist.md @@ -0,0 +1,33 @@ +# Vegbank Release Checklist + +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---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 vx.x.x + + # tag the helm chart release + git tag chart-x.x.x + + # 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 From 0745970b3543d471759962a856b27fd4e8174819 Mon Sep 17 00:00:00 2001 From: Matthew B <106352182+artntek@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:15:02 -0700 Subject: [PATCH 2/5] documenting release process and template --- CONTRIBUTING.md | 31 ++++++++++++++++++------------- README.md | 2 +- release-checklist.md | 2 +- 3 files changed, 20 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d833832..edf038b 100644 --- a/CONTRIBUTING.md +++ b/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. `v2.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: diff --git a/README.md b/README.md index 4c418a2..c39f193 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,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 diff --git a/release-checklist.md b/release-checklist.md index 0b07fad..1569c53 100644 --- a/release-checklist.md +++ b/release-checklist.md @@ -1,4 +1,4 @@ -# Vegbank Release Checklist +# 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. From 911d8eecd5014926a9a8e862d08455881ed7cf21 Mon Sep 17 00:00:00 2001 From: Matthew B <106352182+artntek@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:30:15 -0700 Subject: [PATCH 3/5] remove 'v' from version number/tag --- CONTRIBUTING.md | 2 +- release-checklist.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index edf038b..7192e1d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -117,7 +117,7 @@ the full set of tests on a clean checkout of the `develop` branch. 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. `v2.0.1`) and + 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 diff --git a/release-checklist.md b/release-checklist.md index 1569c53..66d493a 100644 --- a/release-checklist.md +++ b/release-checklist.md @@ -20,7 +20,7 @@ When testing is complete on the develop branch, create a new issue containing th git rev-parse --short HEAD # tag the api code release - git tag vx.x.x + git tag x.x.x # tag the helm chart release git tag chart-x.x.x From 72b5d1c8cd910a568fe5dde7c5d1b9bc475cad9e Mon Sep 17 00:00:00 2001 From: Matthew B <106352182+artntek@users.noreply.github.com> Date: Wed, 1 Apr 2026 13:04:49 -0700 Subject: [PATCH 4/5] update local install notes --- README.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index c39f193..db8a4be 100644 --- a/README.md +++ b/README.md @@ -79,22 +79,20 @@ commits can be run, for example, for the Mac with: We are using `uv` as our python environment and dependency manager. To get started locally, follow these instructions below: ```sh -# Step 1: Set your `VIRTUAL_ENV` path (if not already set) -$ export VIRTUAL_ENV=/data/venv - -# Step 2: Install `uv` (if not already installed) +# Step 1: Install `uv` (if not already installed) $ python -m pip install uv --root-user-action ignore -# Step 3: Navigate to your project root +# Step 2: 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 +# Step 3: Create a project-local virtual environment +$ uv venv .venv -# Step 5: Install all dependencies into the venv -$ uv sync --active +# Step 4: Activate the virtual environment +$ source .venv/bin/activate +# Step 5: Install project dependencies +$ uv sync --active ``` ### Adding project dependencies From b070574abc31b63027bddb66c12f5a869da46dba Mon Sep 17 00:00:00 2001 From: Matthew B <106352182+artntek@users.noreply.github.com> Date: Wed, 1 Apr 2026 13:42:03 -0700 Subject: [PATCH 5/5] update local run instructions --- README.md | 39 +++++++++++++++++++++++++++------------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index db8a4be..1a95a45 100644 --- a/README.md +++ b/README.md @@ -76,23 +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: Install `uv` (if not already installed) -$ python -m pip install uv --root-user-action ignore +#### One-time setup -# Step 2: Navigate to your project root +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) + + ```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 3: Create a project-local virtual environment +# Create a project-local virtual environment $ uv venv .venv -# Step 4: Activate the virtual environment +# Activate the virtual environment $ source .venv/bin/activate -# Step 5: Install project dependencies +# Install project dependencies $ uv sync --active + +# Run the application +uv run flask --app src/vegbank/app.py run ``` ### Adding project dependencies @@ -105,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", @@ -183,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: