<a id="releasing-social-auth-core"></a>

# Releasing social-auth-core

This guide describes the `social-auth-core` release process implemented by
its [release workflow](https://github.com/python-social-auth/social-core/blob/master/.github/workflows/release.yml). Other components may use different workflows; check
their repository documentation before releasing them.

<a id="preparing-a-release"></a>

## Preparing a release

1. Update `project.version` in `pyproject.toml` using the project’s
   [Semantic Versioning](https://semver.org/spec/v2.0.0.html) 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:
   ```default
   ## [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](https://www.conventionalcommits.org/), 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.

<a id="pushing-the-release-tag"></a>

## 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:

```default
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.

<a id="what-ci-publishes"></a>

## 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](https://github.com/python-social-auth/social-core/actions/workflows/release.yml) and verify that both publishing jobs
complete. Check the version and distributions on [PyPI](https://pypi.org/project/social-auth-core/) and the notes and
assets on [GitHub Releases](https://github.com/python-social-auth/social-core/releases). Success on one service does not imply success
on the other.

<a id="handling-a-failed-publication"></a>

## 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.