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,148 @@ 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](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 section. | ||
|
|
||
| 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``). | ||
|
|
||
|
|
||
| Prerequisites | ||
| ````````````` | ||
|
|
||
| In order to be able to release a new pandas version, the next permissions are needed: | ||
|
|
||
| - Merge rights to the [pandas](https://github.com/pandas-dev/pandas/), | ||
| [pandas-wheels](https://github.com/MacPython/pandas-wheels), and | ||
| [pandas-feedstock](https://github.com/conda-forge/pandas-feedstock/) repositories. | ||
| - Permissions to push to main in the pandas repository, to push the new tags. | ||
| - Write permissions to [PyPI](https://github.com/conda-forge/pandas-feedstock/pulls) | ||
| - Access to the social media accounts, to publish the announcements. | ||
|
|
||
| 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 (major/minor releases happen usually every 6 months, and patch releases | ||
| monthly until x.x.5, just before the next major/minor) | ||
| - 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). |
||
| If the release was a release candidate, we would usually want to create issues and | ||
| milestones for both the next major/minor, and the next patch release. In the | ||
| milestone of a patch release, we add the description ``on-merge: backport to <branch>``, | ||
| so tagged PRs are automatically backported to the release branch 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: | ||
|
|
||
| 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 | ||
|
|
||
| The docs for the new version will be built and published automatically with the docs job in the CI, | ||
| which will be triggered when the tag is pushed. | ||
|
|
||
| 2. Only if the release is a release candidate, we want to create a new branch for it, immediately | ||
| after creating the tag. For example, if we are releasing pandas 1.4.0rc0, we would like to | ||
| create the branch 1.4.x to backport commits to the 1.4 versions. As well as create a tag to | ||
| mark the start of the development of 1.5.0 (assuming it is the next version): | ||
|
|
||
| git checkout -b 1.4.x | ||
| git push upstream 1.4.x | ||
| git checkout main | ||
| git commit --allow-empty -m "Start 1.5.0" | ||
| git tag -a v1.5.0.dev0 -m "DEV: Start 1.5.0" | ||
| git push upstream main --follow-tags | ||
|
|
||
| 3. Build the source distribution (git must be in the tag commit): | ||
|
|
||
| ./setup.py sdist --formats=gztar --quiet | ||
|
|
||
| 4. 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. |
||
| - Set as a pre-release: Only check for a release candidate | ||
| - Set as the latest release: Leave checked, unless releasing a patch release for an older version | ||
| (e.g. releasing 1.4.5 after 1.5 has been released) | ||
|
|
||
| 5. 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. | ||
|
|
||
| 6. 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. | ||
|
|
||
| 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> | ||
|
|
||
| 7. 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. | ||
|
|
||
| 8. Upload wheels to PyPI: | ||
|
|
||
| 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.