Release process

The phylum-ci project repository currently makes use of GitHub flow, which is also known as trunk-based development.

Specifically, for this repository, there is a single long-living branch:

• main
  • This is the default branch
  • Feature branches are created from here
  • This is where releases are cut
  • This is a protected branch
  • Release tags should point to this branch
  • Roughly aligns with the "Production" environment

Cutting a release

To cut a release, follow these steps:

1. Go to the Release Workflow for the repo
2. Select the Run workflow dropdown
   1. The workflow can only be run on the main branch
   2. Optionally, select the prerelease checkbox to create a pre-release
3. Click the Run workflow button to trigger a release

Workflows

All automation workflows use GitHub Actions. All workflows are therefore configured using .yml files in the .github/workflows directory of the phylum-ci repository. This section contains descriptions of the release related workflows.

Preview workflow

This workflow creates a developmental release version of the package, runs it against the test suite, and makes the artifacts available for download from the workflow summary. The workflow is triggered on pushes to the main branch or manually from any branch. When using the manual approach, an option is exposed to optionally publish the built package to the TestPyPI repository. From there it can be tested locally in an ephemeral environment. For example, using pipx to run a specific developmental release version:

pipx run -i https://test.pypi.org/simple/ --spec "phylum==0.24.2.dev183" --pip-args="--extra-index-url=https://pypi.org/simple/" phylum-init -h

Release workflow

This is a workflow for releasing packages in GitHub and publishing to PyPI. This workflow is only triggered manually, from the Actions tab. It is limited to those with write access to the repo (e.g., collaborators and orgs, people, teams given write access) and only for the main branch.

The release process leans heavily on the Python Semantic Release (PSR) tool, which in turn is dependent on conventional commits to determine release versions. Poetry is used to build the release distributions in order to use them for "verification" purposes before creating a GitHub release and publishing to PyPI. The rich-codex tool is used to update the script options documentation. PSR will determine the release version, update the change log, commit and push changes (including those from rich-codex) back to the repository, and tag the release. PSR will also generate the GitHub release and populate it with the artifacts as built by poetry. Poetry is used to upload the release to PyPI.

Currently this workflow uses the Production environment, as configured in the repo settings. This holds the PyPI API token as an environment secret. It also makes use of environment protections rules such that there are designated reviewer groups that must approve the deployment.