Versioning and Releases

This page documents the versioning strategy and the steps required to cut a release of drf-flex-fields2.

Versioning Strategy

drf-flex-fields2 follows Semantic Versioning (SemVer). Given a version number MAJOR.MINOR.PATCH:

  • PATCH is incremented for backwards-compatible bug fixes.

  • MINOR is incremented for backwards-compatible new features.

  • MAJOR is incremented for breaking changes to the public API.

There are currently no plans to introduce breaking changes. Users can safely update to any patch or minor release without modifying their code.

Version Baseline

Version 2.0.0 of drf-flex-fields2 is feature-equivalent to version 1.0.2 of the original drf-flex-fields package. It carries a major version of 2 to reflect the modernized tooling, updated minimum requirements, and forked lineage — not because the user-facing API was broken, except for import path changes.

Release Checklist

  1. Ensure main is green.

    All CI checks must pass before tagging.

  2. Create release issue (recommended).

    Create a new issue for the release and describe remaining work to be done before a new version is released. You don’t need to repeat the individual release steps. Just, what else needs to be done.

  3. Create new branch.

    From within the release issue create a new release preparation branch. Checkout the branch as the next steps must all be performed within that branch.

  4. Complete remaining work.

    If there is any remaining work to be done (e.g. updating documentation) push the changes onto the release preparation branch.

  5. Update the changelog.

    Add a dated entry to Change Log summarising user-visible changes. See Changelog Format below for the expected format.

  6. Bump the version number in pyproject.toml using Poetry:

    # choose one of: patch, minor, major
poetry version minor

  7. Commit the version bump:

    git add pyproject.toml docs/reference/changelog.rst
git commit -m "Bump version: vX.Y.Z"

  8. Open and merge pull request.

    Now open a pull request to merge the release preparation branch into main. At this stage Copilot will review the branch, code quality and security will be scanned, documentation will be built, and unit tests will run. Usually you will need to push a few more commits to the release branch (which will automatically appear in the PR and retrigger quality checks).

    Once all is green, merge the pull request into main.

  9. Tag the commit in order to trigger the release workflow.

    Checkout the main branch and create a signed annotated tag for the merge commit, then push the tag to GitHub:

    git checkout main
git pull
git tag -s vX.Y.Z -m "Release vX.Y.Z"
git push origin --tags

    The .github/workflows/release.yml workflow will automatically:

    • Verify the tag is a signed annotated tag with a valid signature

    • Verify the tag version matches pyproject.toml

    • Run the full test suite and build the documentation again (for safety)

    • Build source distribution (.tar.gz) and wheel (.whl) artifacts

    • Generate a CycloneDX SBOM (sbom.cyclonedx.json)

    • Create a GitHub release with release notes extracted from the changelog

    • Publish the package to PyPI

    Monitor the workflow run in the Actions tab.

Changelog Format

The changelog is located in docs/reference/changelog.rst and uses reStructuredText (RST) formatting. Each version entry must follow this structure, allowing the release workflow to extract the changelog entries for the GitHub release page.

X.Y.Z (Month Year)
^^^^^^^^^^^^^^^^^^

- Change 1
- Change 2
- Change 3

Guidelines:

  • Use the exact version number (e.g., 2.1.0) without the v prefix.

  • Add the release date in parentheses (e.g., (April 2026)).

  • Add underline using ^ characters of same length.

  • List changes as bullet points with clear, user-facing descriptions.

  • Start descriptions with the affected component (e.g., “Fixed bug in FlexFieldsFilterBackend…”).

  • Group related changes together logically.

Pre-releases:

For pre-release versions (alpha, beta, release candidate), use the extended version format in the tag and changelog:

git tag v2.1.0-pre1
git tag v2.1.0-rc1

Update the changelog accordingly:

2.1.0-pre1 (April 2026)
^^^^^^^^^^^^^^^^^^^^^^^

- Preview of upcoming features...

The release workflow will automatically detect pre-releases and mark them as such in GitHub.

Tag Signing

Setup

Release tags must be signed. If tag signing is not configured locally, set it up once before creating your next release:

# Use your existing GPG key ID
git config --global user.signingkey <YOUR_GPG_KEY_ID>
git config --global tag.gpgSign true

To list available secret keys and find your key ID:

gpg --list-secret-keys --keyid-format=long

Only signed annotated tags (git tag -s) are accepted by the release workflow.

Signing commits is also recommended as a general repository security practice, but commit signing is currently not enforced by the release workflow.

Troubleshooting

If the release workflow rejects a signed tag with a reason such as bad_email, inspect the tag metadata first:

git cat-file -p <tag>

Look for the tagger line, for example:

tagger Name <email@example.com> ...

When you create a signed tag with git tag -s, Git embeds the tagger identity from your local Git configuration. That email address must:

  • Be present in your GitHub account

  • Be verified in GitHub

  • Match exactly, including casing

A common failure mode is that GitHub has multiple verified email addresses, but Git is using the wrong one via user.email. This matters because Git uses that email for the tagger identity, while GPG signs with a key that is usually associated with specific UID email addresses. If the tagger email and the verified GitHub identity do not align, GitHub tag verification can fail.

To fix this, delete the incorrect tag locally and remotely, correct your Git identity, then recreate and push the signed tag:

git tag -d <tag>
git push origin :refs/tags/<tag>

git config user.email <correct-verified-email>
git tag -s <tag>
git push origin <tag>

Read the Docs

Documentation is rebuilt automatically on every push to main and on every tag that matches the v* pattern. No manual trigger is needed after pushing a release tag. See Repository and Tooling Setup for details of the Read the Docs project settings and automation rules.