Releasing social-auth-core

This guide describes the social-auth-core release process implemented by its release workflow. Other components may use different workflows; check their repository documentation before releasing them.

Preparing a release

1. Update project.version in pyproject.toml using the project’s Semantic Versioning policy.

2. Review the Unreleased entries in CHANGELOG.md and include any missing changes. Move the release’s entries into a section matching the package version, with a release link and date. Leave an empty Unreleased section above it. For example:

   ## [Unreleased]
   
   ## [7.2.0](https://github.com/python-social-auth/social-core/releases/tag/7.2.0) - 2026-11-12
   
   ### Added
   
   - Describe the changes included in this release.
   

3. Commit the preparation using Conventional Commits, for example chore: release 7.2.0, and open a pull request against master. Complete the pull request template and request review from the maintainers.

4. Merge the reviewed release pull request after its checks pass.

Pushing the release tag

Create the version tag on the merged release commit and push that tag to the upstream repository. For example, with origin pointing to the upstream python-social-auth/social-core repository:

git switch master
git pull --ff-only origin master
git tag -a 7.2.0 <release-commit-sha> -m "Release 7.2.0"
git push origin 7.2.0

Replace the example version and <release-commit-sha> with the intended version and merged release commit. Verify that the tagged commit contains the matching package version and a nonempty changelog section. Existing core tags use the bare version number; the workflow also accepts a leading v when looking up changelog notes.

Push the tag first. Do not create or publish a release through GitHub’s Draft a new release interface to start this process. The workflow runs on tag pushes, and creating a release in advance conflicts with its release creation step. Publishing an empty immutable release also prevents CI from adding the distribution assets afterward.

What CI publishes

The workflow builds a wheel and source distribution, rebuilds a wheel from the source distribution, and checks installation, metadata, and distribution contents. Once these checks pass, two independent jobs publish the artifacts:

• The PyPI job publishes the validated distributions from the upstream repository using trusted publishing through the pypi environment, with attestations enabled.

• The GitHub job extracts the tagged version’s notes from CHANGELOG.md, creates a draft release with the wheel and source distribution attached, and then publishes the draft. Uploading all assets before publication supports immutable releases.

Monitor the Release workflow runs and verify that both publishing jobs complete. Check the version and distributions on PyPI and the notes and assets on GitHub Releases. Success on one service does not imply success on the other.

Handling a failed publication

Inspect the failed job and the publication state on both services before retrying. The GitHub job refuses to overwrite any existing release for the tag, including a draft. If it left an incomplete draft, inspect and remove that draft before retrying the failed GitHub job.

A published immutable release cannot have its distribution assets replaced. Asset corrections require a new version and tag. Do not move the published tag or try to replace its assets. When retrying a failed job, account for the other publishing job having already succeeded.