Build and release

The document outlines the steps to build and release the deeptab package. At this point, it is assumed that the development and testing of the package have been completed successfully.

Release workflow

        %%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#dbeafe',
  'primaryTextColor': '#1e3a5f',
  'primaryBorderColor': '#3b82f6',
  'lineColor': '#6b7280',
  'secondaryColor': '#ede9fe',
  'tertiaryColor': '#f0fdf4',
  'edgeLabelBackground': '#f9fafb'
}}}%%
flowchart TD
    A[Create release/vX.Y.Z branch]:::setup --> B{Release type?}:::decision
    B -->|RC| RC1[Bump version e.g. 1.7.0rc1]:::setup
    B -->|Stable| ST1[Bump version e.g. 1.7.0]:::setup
    RC1 --> RC2[Update CHANGELOG.md]:::setup
    RC2 --> RC3[Commit & push branch]:::setup
    RC3 --> RC4["git tag vX.Y.ZrcN<br/>git push origin vX.Y.ZrcN"]:::git
    RC4 --> RC5[CI: publish-testpypi.yml]:::ci
    RC5 --> RC6[TestPyPI + GitHub pre-release]:::rc
    RC6 -->|Issues found| RC1
    RC6 -->|RC approved| ST1
    ST1 --> ST2[Update CHANGELOG.md]:::setup
    ST2 --> ST3[Commit & push branch]:::setup
    ST3 --> ST4[Open PR: release/vX.Y.Z → main]:::pr
    ST4 --> ST5{Review & approve}:::decision
    ST5 --> ST6[Merge PR into main]:::pr
    ST6 --> ST7[git checkout main && git pull]:::git
    ST7 --> ST8["git tag vX.Y.Z<br/>git push origin vX.Y.Z"]:::git
    ST8 --> ST9[CI: publish-pypi.yml]:::ci
    ST9 --> ST10[PyPI + GitHub Release]:::stable

    classDef setup   fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
    classDef pr      fill:#ede9fe,stroke:#8b5cf6,color:#3b0764
    classDef decision fill:#fef9c3,stroke:#ca8a04,color:#713f12
    classDef git     fill:#f0fdf4,stroke:#22c55e,color:#14532d
    classDef ci      fill:#fff7ed,stroke:#f97316,color:#7c2d12
    classDef rc      fill:#fdf4ff,stroke:#d946ef,color:#701a75
    classDef stable  fill:#ecfdf5,stroke:#10b981,color:#064e3b

1. Test documentation

It is expected from the contributor to update the documentation as an when required along side the change in source code. Please use the below process to test the documentation:

cd docs/

make doctest

Fix any docstring related issue, then proceed with next steps.

2. Version update

See Versioning for the full explanation of SemVer rules, commit types, and how cz bump works. The commands are summarised below.

For a stable release — let cz bump derive the next version automatically from conventional commits:

cz bump

This will:

  • Determine the next version from conventional commits since the last tag

  • Update the version in pyproject.toml

  • Update CHANGELOG.md

  • Create a local commit bump: version X.Y.Z-1 → X.Y.Z

For a release candidate — set the version explicitly (e.g. 1.7.0rc1):

poetry version 1.7.0rc1
poetry lock

Then update CHANGELOG.md manually and commit:

git add pyproject.toml poetry.lock CHANGELOG.md
git commit -m "bump: version 1.6.1 → 1.7.0rc1"

The version number follows the format major.minor.patch for stable, or major.minor.patchrcN for release candidates.

3. Tag and publish a release candidate

RC tags are pushed directly from the release branch — no PR to main required.

git tag -a vX.Y.ZrcN -m "Release candidate vX.Y.ZrcN"
git push origin vX.Y.ZrcN

This triggers publish-testpypi.yml, which publishes to TestPyPI and creates a GitHub pre-release.

If issues are found, fix them on the release branch, bump to the next RC (rcN+1), and repeat.

4. Release PR (stable only)

Once all RCs are approved, open a PR from release/vX.Y.Z to main:

  • After review and approval, merge the PR

  • Merging to main does NOT trigger a PyPI release

Promoting a model from experimental to stable? Verify the Model Promotion Policy checklist is complete before merging a release PR that includes a promotion.

5. Create and push the stable tag

After the release PR is merged:

git checkout main && git pull
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

6. Publish package

The tag push automatically triggers the appropriate GitHub Actions workflow — see CI/CD for the full workflow details. In summary:

  • Stable tag (vX.Y.Z) → publish-pypi.yml → PyPI + GitHub Release

  • RC tag (vX.Y.ZrcN) → publish-testpypi.yml → TestPyPI + GitHub pre-release

Both workflows use OIDC Trusted Publishing (no API tokens required).

7. GitHub Release

The GitHub Release is created automatically by the publish workflow. Verify the release notes are correct and add any manual context if needed.