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?

[AndrewSazonov]

Release Workflow Diagram

The following diagram summarizes the key steps of the release workflow after the develop branch is prepared for a new release. Some substeps are described in further detail in the corresponding sections.

---
config:
  kanban:
    ticketBaseUrl: 'https://github.com/easyscience/peasy-lib/blob/master/.github/workflows/#TICKET#'
---

kanban
  [1. Create Release PR<br/> 👤 Human, 🤖 Automated]
    Create a PR from _develop_ to _master_ via manual workflow dispatch @{ticket: release-pr.yml, assigned: 📜}

  [2. CI Checks<br/> 🤖 Automated]
    PR label validation @{ticket: pr-labels.yml, assigned: 📜}
    Code quality checks @{ticket: quality.yml, assigned: 📜}
    Code and package tests @{ticket: test.yml, assigned: 📜}
    Tutorial tests @{ticket: tutorial-tests.yml, assigned: 📜}
    Coverage checks @{ticket: coverage.yml, assigned: 📜}
    Documentation build @{ticket: docs.yml, assigned: 📜}
    Security analysis @{ticket: security.yml, assigned: 📜}

  [3. Review and Merge<br/> 👤 Human]
    Review CI results
    Approve and merge the PR

  [4. Prepare Release Draft<br/> 🤖 Automated]
    Release draft creation @{ticket: release-notes.yml, assigned: 📜}

  [5. Publish Release<br/> 👤 Human]
    Review tag/version,<br/>_created based on PR labels_
    Review release title,<br/>_created from template_
    Review release notes,<br/>_created and grouped based on PR titles_
    Mark as a prerelease if needed
    Publish the release

  [6. Post Release Actions<br/> 🤖 Automated]
    PyPI publication @{ticket: pypi-publish.yml, assigned: 📜}
    Documentation build and deployment @{ticket: docs.yml, assigned: 📜}
    Backmerge from _master_ to _develop_ @{ticket: backmerge.yml, assigned: 📜}

Loading