ADR Suggestion Unified Release Workflow with Explicit Human Approval

[AndrewSazonov]

The goal of this ADR is to define a common and consistent release workflow for all products developed under the EasyScience organization.

The main idea is to keep the process largely automated, but split it into several clear steps with intentional human approval points. This gives us both safety and consistency: automation handles repetitive tasks, while developers stay in control of important decisions.

The overall branching model (feature → develop → master) is described in ADR #12.
The steps below describe what happens once the develop branch is ready for a new release.

Proposed release workflow

1. 👤 Human: Create release PR (develop → master)

A pull request from develop to master is created to start the release process.

This can be done:

• fully manually (select branches, write title/description, add labels), or
• semi-automatically using the helper workflow described in `ADR Suggestion` Auto-generated Release Pull Requests (develop → master) #50, which pre-fills title, description, and labels.

This step is an intentional human action.

2. 🤖 Auto: CI checks on the release PR

Creating the PR automatically triggers a full set of CI workflows, including:

• PR label checks
• Code quality checks, defined in pyproject.toml and prettierrc.toml configs:
  • Python linting and formatting (ruff)
  • Docstring checks (interrogate)
  • Notebook formatting
  • Non-Python formatting (prettier)
• Code and package tests:
  • Unit tests
  • Functional / integration tests
  • Tests of the built package on a clean machine
  • Run on multiple platforms (Windows, macOS, Linux)
  • Run on minimum and maximum supported Python versions
• Tutorial tests, to ensure tutorials can at least be executed
• Coverage checks:
  • Unit and integration test coverage
  • Upload to Codecov
  • Docstring coverage
• Documentation build:
  • Build docs
  • Upload as artifact
  • Deploy to a temporary dev docs URL (for example:
    https://easyscience.github.io/peasy-lib/dev)
• Open-source static security analysis

3. 👤 Human: Review and merge PR

When all CI checks are green, a maintainer explicitly reviews and merges the PR using the GitHub web interface.

This is another intentional human approval step.

4. 🤖 Auto: Prepare release draft

Merging into master automatically triggers workflows that:

• Create a release draft
• Generate release notes
• Suggest a new version/tag, based on:
  • PR labels
  • PR titles
  • Changes merged into master (via develop or directly)

5. 👤 Human: Review and publish release

A maintainer opens the release draft on the GitHub Releases page and:

• Reviews the suggested version and release notes
• Marks it as pre-release if needed
• Clicks “Publish release”

Again, this step requires explicit human approval.

6. 🤖 Auto: Post-release actions

Publishing the release automatically triggers:

• PyPI publishing (build and upload the Python package)
• Documentation build and deployment:
  • Build docs for the released version
  • Deploy under a versioned URL, for example:
    https://easyscience.github.io/peasy-lib/v1.2.0
• Backmerge from master back to develop, as described in `ADR Suggestion` Automated backmerge from `master` to `develop` on release tags #44

Summary

The full release process is automated between approval points, but still requires humans to:

• start the release,
• approve the release PR,
• publish the final release.

[damskii9992]

Makes sense. I approve.

My only question is, where is our (yet to exist) workflow which inspects the [scope] labels and adjust the version appropriately?