Standardized release workflow

[AndrewSazonov]

This defines a common and consistent release workflow for all products developed under the EasyScience organization.

The main idea is to keep the process largely automated, while splitting it into clearly defined steps with intentional manual approval points. This provides both safety and consistency: automation handles repetitive and error-prone tasks, while developers remain in control of important decisions.

The overall branching model (feature → develop → master) is described in ADR #12.

The diagram below shows the top-level release workflow steps after the develop branch is prepared for a new release. Each column represents one major step. Substeps details are given in the corresponding sections below.

Release Workflow Diagram

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

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

  [2. CI Checks<br/> 🤖 Automated]
    PR labels 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 _master_ to _develop_ @{ticket: backmerge.yml, assigned: 📜}

Loading

Release Workflow Details

1. Create release PR (develop → master)

The release process starts by creating a pull request from develop to master.

This is triggered manually via the GitHub Actions tab using the workflow:
Release PR (develop → master).

See ADR #57 for more details.

2. CI checks

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

• PR label validation
• Code quality checks, defined in pyproject.toml and prettierrc.toml:
  • 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 environment
  • Executed on multiple platforms (Windows, macOS, Linux)
  • Executed on minimum and maximum supported Python versions
• Tutorial tests:
  • Ensuring tutorials can at least be executed
• Coverage checks:
  • Unit and functional / integration test coverage
  • Upload to Codecov
  • Docstring coverage
• Documentation build:
  • Build documentation
  • Upload as artifact
  • Deploy to a temporary dev URL, for example:
    https://easyscience.github.io/peasy-lib/dev
• Open-source static security analysis

All checks must pass before the PR can be merged.

3. Review and Merge

When all CI checks are green, a maintainer explicitly:

• Reviews the PR and CI results
• Manually clicks Merge in the GitHub web interface

This manual approval is an intentional control point.

4. Prepare Release Draft

Merging into master automatically triggers workflow that create a release draft with:

• A suggested new version/tag, based on PR labels (merged to develop)
• A generated release title based on a template
• A generated release notes, grouped based on PR titles

This ensures consistent and automated release preparation.

5. 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”

This is the second intentional manual approval step.

6. Post-Release Actions

Publishing the release automatically triggers:

• PyPI publishing
  • Build and upload the Python package to PyPI
• 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 `ADR Suggestion` Automated backmerge from `master` to `develop` on release tags #44.

Summary

The full release process is automated between clearly defined manual approval points, but still requires human actions to:

• Start the release process
• Approve and merge the release PR
• Review and publish the final release

---

Links to the original discussions: #54