From f0dc8a3bf5f0003c2aafdf3b6558e1ea71485bdd Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Wed, 23 Nov 2022 13:21:20 +0700 Subject: [PATCH 1/3] DOC: Add release process --- doc/source/development/maintaining.rst | 121 ++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 1 deletion(-) diff --git a/doc/source/development/maintaining.rst b/doc/source/development/maintaining.rst index df557585c6156..16adec7beca7b 100644 --- a/doc/source/development/maintaining.rst +++ b/doc/source/development/maintaining.rst @@ -345,7 +345,126 @@ The benchmarks are scheduled by Airflow. It has a dashboard for viewing and debu Release process --------------- -The process for releasing a new version of pandas can be found at https://github.com/pandas-dev/pandas-release +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: + +- Git repo with a new tag +- 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. + +The instructions contain ```` which needs to be replaced with the version +to be released (e.g. ``1.5.2``). Also the branch to be released ````, 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 +``````````` + +1. Agree with the core team on the next topics: + + - Release date + - 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. + Add the description ``on-merge: backport to `` 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 +git pull --ff-only upstream +git clean -xdf +git commit --allow-empty --author="Pandas Development Team " -m "RLS: " +git tag -a v -m "Version " # NOTE that the tag is v1.5.2 with `v` not 1.5.2 +git push upstream --follow-tags +``` + +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 `` + - Tag: ```` + - Files: ``pandas-.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) + +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- + +sed -i 's/BUILD_COMMIT: "v.*/BUILD_COMMIT: "''"/' azure/windows.yml azure/posix.yml +sed -i 's/BUILD_COMMIT="v.*/BUILD_COMMIT="''"/' .travis.yml + +git commit -am "RLS " + +git push -u origin RLS- +``` + +6. Download all wheels from the Anaconda repository where MacPython uploads them: + https://anaconda.org/multibuild-wheels-staging/pandas/files?version= + to the ``dist/`` directory in the local pandas copy. + +7. Upload wheels to PyPI: + +```sh +twine upload pandas/dist/pandas-*.{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 From f3f8e3624a3fe605e6fbc3f8cbc04d1b00d9498b Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Fri, 25 Nov 2022 23:29:24 +0700 Subject: [PATCH 2/3] Update doc/source/development/maintaining.rst Co-authored-by: Matthew Roeschke <10647082+mroeschke@users.noreply.github.com> --- doc/source/development/maintaining.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/development/maintaining.rst b/doc/source/development/maintaining.rst index 16adec7beca7b..9f832921d292d 100644 --- a/doc/source/development/maintaining.rst +++ b/doc/source/development/maintaining.rst @@ -354,7 +354,7 @@ in the next places: - 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. +The process for releasing a new version of pandas is detailed next section. The instructions contain ```` which needs to be replaced with the version to be released (e.g. ``1.5.2``). Also the branch to be released ````, which From 6126e90eded5b874db1b7d089f0fa4b4b636598c Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Fri, 25 Nov 2022 23:59:12 +0700 Subject: [PATCH 3/3] Addressing review comments --- doc/source/development/maintaining.rst | 94 ++++++++++++++++---------- 1 file changed, 58 insertions(+), 36 deletions(-) diff --git a/doc/source/development/maintaining.rst b/doc/source/development/maintaining.rst index 16adec7beca7b..ace2f20d277bc 100644 --- a/doc/source/development/maintaining.rst +++ b/doc/source/development/maintaining.rst @@ -349,7 +349,7 @@ The release process makes a snapshot of pandas (a git commit) available to users a particular version number. After the release the new pandas version will be available in the next places: -- Git repo with a new tag +- 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) @@ -363,12 +363,25 @@ 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 ``````````` 1. Agree with the core team on the next topics: - - Release date + - 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 @@ -384,8 +397,10 @@ Pre-release being released are merged. 5. Create a new issue and milestone for the version after the one being released. - Add the description ``on-merge: backport to `` to the milestone, so tagged - PRs are automatically backported by our bot. + 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 ``, + 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. @@ -395,59 +410,66 @@ Release 1. Create an empty commit and a tag in the last commit of the branch to be released: -```sh -git checkout -git pull --ff-only upstream -git clean -xdf -git commit --allow-empty --author="Pandas Development Team " -m "RLS: " -git tag -a v -m "Version " # NOTE that the tag is v1.5.2 with `v` not 1.5.2 -git push upstream --follow-tags -``` + git checkout + git pull --ff-only upstream + git clean -xdf + git commit --allow-empty --author="Pandas Development Team " -m "RLS: " + git tag -a v -m "Version " # NOTE that the tag is v1.5.2 with "v" not 1.5.2 + git push upstream --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. Build the source distribution (git must be in the tag commit): +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): -```sh -./setup.py sdist --formats=gztar --quiet -``` + 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. Create a [new GitHub release](https://github.com/pandas-dev/pandas/releases/new): +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 `` - Tag: ```` - Files: ``pandas-.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) + - 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) -4. The GitHub release will after some hours trigger an +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. -5. Packages for supported versions in PyPI are built in the +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. -```sh -git checkout master -git pull --ff-only upstream master -git checkout -B RLS- - -sed -i 's/BUILD_COMMIT: "v.*/BUILD_COMMIT: "''"/' azure/windows.yml azure/posix.yml -sed -i 's/BUILD_COMMIT="v.*/BUILD_COMMIT="''"/' .travis.yml - -git commit -am "RLS " - -git push -u origin RLS- -``` + git checkout master + git pull --ff-only upstream master + git checkout -B RLS- + sed -i 's/BUILD_COMMIT: "v.*/BUILD_COMMIT: "''"/' azure/windows.yml azure/posix.yml + sed -i 's/BUILD_COMMIT="v.*/BUILD_COMMIT="''"/' .travis.yml + git commit -am "RLS " + git push -u origin RLS- -6. Download all wheels from the Anaconda repository where MacPython uploads them: +7. Download all wheels from the Anaconda repository where MacPython uploads them: https://anaconda.org/multibuild-wheels-staging/pandas/files?version= to the ``dist/`` directory in the local pandas copy. -7. Upload wheels to PyPI: +8. Upload wheels to PyPI: -```sh -twine upload pandas/dist/pandas-*.{whl,tar.gz} --skip-existing -``` + twine upload pandas/dist/pandas-*.{whl,tar.gz} --skip-existing Post-Release ````````````