From 21a8643cc2e37a3f639b2efc45cabdb75db1c8d2 Mon Sep 17 00:00:00 2001 From: Matt Savoie Date: Tue, 30 Jul 2024 12:24:30 -0600 Subject: [PATCH] DAS-2180: Clarify releases. --- README.md | 57 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index cdae1f8..5a0fd0d 100644 --- a/README.md +++ b/README.md @@ -249,9 +249,8 @@ also with units of degrees. * `docker` - A directory containing the Dockerfiles for the service and test images. It also contains `service_version.txt`, which contains the semantic - version number of the library and service image. Any time an update is made - that should have an accompanying library and service image release, this file - should be updated. + version number of the library and service image. Update this file with a new + version to trigger a release. * `docs` - A directory with example usage notebooks. @@ -340,28 +339,21 @@ Currently, the `unittest` suite is run automatically within a GitHub workflow as part of a CI/CD pipeline. These tests are run for all changes made in a PR against the `main` branch. The tests must pass in order to merge the PR. -Unit tests are executed automatically before publishing new library packages -and Docker images. This occurs when commits containing changes to -`docker/service_version.txt` are merged into the `main` branch. Failed unit -tests prevent the publication of new Docker images and library packages. +Unit tests are executed automatically by github actions on each Pull Request. + ## Versioning: -Service Docker images and the package library for HyBIG adhere to semantic +Docker service images and the hybig-py package library adhere to semantic version numbers: major.minor.patch. * Major increments: These are non-backwards compatible API changes. * Minor increments: These are backwards compatible API changes. * Patch increments: These updates do not affect the API to the service. -When publishing a new release, two files must be updated: - -* `CHANGELOG.md` - Notes should be added to capture the changes to the service. -* `docker/service_version.txt` - The semantic version number should be updated. - ## CI/CD: -The CI/CD for HyBIG is contained in GitHub workflows in the +The CI/CD for HyBIG is run on github actions with the workflows in the `.github/workflows` directory: * `run_lib_tests.yml` - A reusable workflow that tests the library functions @@ -376,23 +368,34 @@ The CI/CD for HyBIG is contained in GitHub workflows in the `main` branch that contain changes to the `docker/service_version.txt` file. * `publish_to_pypi.yml` - Triggered either manually or for commits to the `main` branch that contain changes to the `docker/service_version.txt`file. +* `publish_release.yml` - workflow runs automatically when there is a change to + the `docker/service_version.txt` file on the main branch. This workflow will: + * Run the full unit test suite, to prevent publication of broken code. + * Extract the semantic version number from `docker/service_version.txt`. + * Extract the released notes for the most recent version from `CHANGELOG.md`. + * Build and deploy a this service's docker image to `ghcr.io`. + * Build the library package to be published to PyPI. + * Publish the package to PyPI. + * Publish a GitHub release under the semantic version number, with associated + git tag. -The `publish_release.yml` workflow will: -* Run the full unit test suite, to prevent publication of broken code. -* Extract the semantic version number from `docker/service_version.txt`. -* Extract the released notes for the most recent version from `CHANGELOG.md`. -* Build and deploy a this service's docker image to `ghcr.io`. -* Build the library package to be published to PyPI. -* Publish the package to PyPI. -* Publish a GitHub release under the semantic version number, with associated - git tag. +## Releasing +A release consists of a new version hybig-py library published to PyPI and a +new Docker service image published to github's container repository. + +A release is made automatically when a commit to the main branch contains a +changes in the `docker/service_version.txt` file, see the [publish_release](#release-workflow) workflow in the CI/CD section above. + +Before merging a PR that will trigger a release, ensure these two files are updated: + +* `CHANGELOG.md` - Notes should be added to capture the changes to the service. +* `docker/service_version.txt` - The semantic version number should be updated. -Before triggering a release, ensure both the `docker/service_version.txt` and -`CHANGELOG.md` files are updated. The `CHANGELOG.md` file requires a specific -format for a new release, as it looks for the following string to define the -newest release of the code (starting at the top of the file). +The `CHANGELOG.md` file requires a specific format for a new release, as it +looks for the following string to define the newest release of the code +(starting at the top of the file). ``` ## [vX.Y.Z] - YYYY-MM-DD