DOC: Add release process to the docs #49858
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -345,7 +345,126 @@ The benchmarks are scheduled by Airflow. It has a dashboard for viewing and debu | |
| Release process | ||
| --------------- | ||
|
|
||
| The release process makes a snapshot of pandas (a git commit) available to users with | ||
| a particular version number. After the release the new pandas version will be available | ||
| in the next places: | ||
|
|
||
|
There was a problem hiding this comment. It would be nice to add a prerequisites section, detailing what sort of permissions you need to release and how to ask for them. |
||
| - Git repo with a new tag | ||
|
There was a problem hiding this comment. Would be good to link to https://github.com/pandas-dev/pandas/tags |
||
| - Source distribution in a [GitHub release](https://github.com/pandas-dev/pandas/releases) | ||
| - Pip packages in the [PyPI](https://pypi.org/project/pandas/) | ||
| - Conda/Mamba packages in [conda-forge](https://anaconda.org/conda-forge/pandas) | ||
|
|
||
| The process for releasing a new version of pandas is detailed next. | ||
datapythonista marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The instructions contain ``<version>`` which needs to be replaced with the version | ||
| to be released (e.g. ``1.5.2``). Also the branch to be released ``<branch>``, which | ||
| depends on whether the version being released is the release candidate of a new version, | ||
| or any other version. Release candidates are released from ``main``, while other | ||
| versions are released from their branch (e.g. ``1.5.x``). | ||
|
|
||
|
|
||
| Pre-release | ||
|
There was a problem hiding this comment. It would be good to have a section on cutting new branches, detailing what needs to be updated in the CI and when to do it(I don't remember if we cut during release, or do it before the release and start backporting). |
||
| ``````````` | ||
|
|
||
| 1. Agree with the core team on the next topics: | ||
|
|
||
| - Release date | ||
|
There was a problem hiding this comment. It would be nice to mention the usual release cadence for patch/minor releases. |
||
| - Blockers (issues and PRs that must be part of the release) | ||
| - Next version after the one being released | ||
|
|
||
| 2. Update and clean release notes for the version to be released, including: | ||
|
|
||
| - Set the final date of the release | ||
| - Remove any unused bullet point | ||
| - Make sure there are no formatting issues, typos, etc. | ||
|
|
||
| 3. Make sure the CI is green for the last commit of the branch being released. | ||
|
|
||
| 4. If not a release candidate, make sure all backporting pull requests to the branch | ||
| being released are merged. | ||
|
|
||
| 5. Create a new issue and milestone for the version after the one being released. | ||
|
There was a problem hiding this comment. After a minor/major release, you would need to create two milestones, right? One for the patch release (e.g. 1.5.1) and one for the next major version (e.g. 2.0.0). |
||
| Add the description ``on-merge: backport to <branch>`` to the milestone, so tagged | ||
| PRs are automatically backported by our bot. | ||
|
|
||
| 6. Change the milestone of all issues and PRs in the milestone being released to the | ||
| next milestone. | ||
|
|
||
| Release | ||
| ``````` | ||
|
|
||
| 1. Create an empty commit and a tag in the last commit of the branch to be released: | ||
|
|
||
| ```sh | ||
| git checkout <branch> | ||
| git pull --ff-only upstream <branch> | ||
| git clean -xdf | ||
| git commit --allow-empty --author="Pandas Development Team <[email protected]>" -m "RLS: <version>" | ||
| git tag -a v<version> -m "Version <version>" # NOTE that the tag is v1.5.2 with `v` not 1.5.2 | ||
| git push upstream <branch> --follow-tags | ||
| ``` | ||
|
There was a problem hiding this comment. It would be nice to mention that the docs get uploaded automatically from the commit that you tag from. |
||
|
|
||
| 2. Build the source distribution (git must be in the tag commit): | ||
|
|
||
| ```sh | ||
| ./setup.py sdist --formats=gztar --quiet | ||
| ``` | ||
|
|
||
| 3. Create a [new GitHub release](https://github.com/pandas-dev/pandas/releases/new): | ||
|
|
||
| - Title: ``Pandas <version>`` | ||
| - Tag: ``<version>`` | ||
| - Files: ``pandas-<version>.tar.gz`` source distribution just generated | ||
| - Description: Copy the description of the last release of the same kind (release candidate, major/minor or patch release) | ||
|
There was a problem hiding this comment. Also mention "Set as release/pre-release" checkboxes should be marked accordingly. |
||
|
|
||
| 4. The GitHub release will after some hours trigger an | ||
| [automated conda-forge PR](https://github.com/conda-forge/pandas-feedstock/pulls). | ||
| Merge it once the CI is green, and it will generate the conda-forge packages. | ||
|
|
||
| 5. Packages for supported versions in PyPI are built in the | ||
| [MacPython repo](https://github.com/MacPython/pandas-wheels). | ||
| Open a PR updating the build commit to the released version, and merge it once the | ||
| CI is green. | ||
|
|
||
| ```sh | ||
| git checkout master | ||
| git pull --ff-only upstream master | ||
| git checkout -B RLS-<version> | ||
|
|
||
| sed -i 's/BUILD_COMMIT: "v.*/BUILD_COMMIT: "'<version>'"/' azure/windows.yml azure/posix.yml | ||
| sed -i 's/BUILD_COMMIT="v.*/BUILD_COMMIT="'<version>'"/' .travis.yml | ||
|
|
||
| git commit -am "RLS <version>" | ||
|
|
||
| git push -u origin RLS-<version> | ||
| ``` | ||
|
|
||
| 6. Download all wheels from the Anaconda repository where MacPython uploads them: | ||
| https://anaconda.org/multibuild-wheels-staging/pandas/files?version=<version> | ||
| to the ``dist/`` directory in the local pandas copy. | ||
|
|
||
| 7. Upload wheels to PyPI: | ||
|
|
||
| ```sh | ||
| twine upload pandas/dist/pandas-<version>*.{whl,tar.gz} --skip-existing | ||
| ``` | ||
|
|
||
| Post-Release | ||
| ```````````` | ||
|
|
||
| 1. Close the milestone and the issue for the released version. | ||
|
|
||
| 2. Create a new issue for the next release, with the estimated date or release. | ||
|
|
||
| 3. Open a PR with the placeholder for the release notes of the next version. See | ||
| for example [the PR for 1.5.3](https://github.com/pandas-dev/pandas/pull/49843/files). | ||
|
|
||
| 4. Announce the new release in the official channels (use previous announcements | ||
| for reference): | ||
|
|
||
| - The pandas-dev and pydata mailing lists | ||
| - Twitter, Mastodon and Telegram | ||
|
|
||
|
|
||
| .. _governance documents: https://github.com/pandas-dev/pandas-governance | ||
| .. _list of permissions: https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any ideas/plans for the old release repo?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd personally archive it once this is merged, and delete it once we released once or twice without using it.
We may want to move couple of scripts here before that happens, for example to automatically download all the wheels, if we don't automate it in the CI before.