Skip to content

Commit adaffe9

Browse files
DOC: Add release process to the docs (#49858)
* DOC: Add release process * Update doc/source/development/maintaining.rst Co-authored-by: Matthew Roeschke <[email protected]> * Addressing review comments Co-authored-by: Matthew Roeschke <[email protected]>
1 parent 3b09765 commit adaffe9

File tree

1 file changed

+142
-1
lines changed

1 file changed

+142
-1
lines changed

doc/source/development/maintaining.rst

+142-1
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,148 @@ The benchmarks are scheduled by Airflow. It has a dashboard for viewing and debu
345345
Release process
346346
---------------
347347

348-
The process for releasing a new version of pandas can be found at https://github.com/pandas-dev/pandas-release
348+
The release process makes a snapshot of pandas (a git commit) available to users with
349+
a particular version number. After the release the new pandas version will be available
350+
in the next places:
351+
352+
- Git repo with a [new tag](https://github.com/pandas-dev/pandas/tags)
353+
- Source distribution in a [GitHub release](https://github.com/pandas-dev/pandas/releases)
354+
- Pip packages in the [PyPI](https://pypi.org/project/pandas/)
355+
- Conda/Mamba packages in [conda-forge](https://anaconda.org/conda-forge/pandas)
356+
357+
The process for releasing a new version of pandas is detailed next section.
358+
359+
The instructions contain ``<version>`` which needs to be replaced with the version
360+
to be released (e.g. ``1.5.2``). Also the branch to be released ``<branch>``, which
361+
depends on whether the version being released is the release candidate of a new version,
362+
or any other version. Release candidates are released from ``main``, while other
363+
versions are released from their branch (e.g. ``1.5.x``).
364+
365+
366+
Prerequisites
367+
`````````````
368+
369+
In order to be able to release a new pandas version, the next permissions are needed:
370+
371+
- Merge rights to the [pandas](https://github.com/pandas-dev/pandas/),
372+
[pandas-wheels](https://github.com/MacPython/pandas-wheels), and
373+
[pandas-feedstock](https://github.com/conda-forge/pandas-feedstock/) repositories.
374+
- Permissions to push to main in the pandas repository, to push the new tags.
375+
- Write permissions to [PyPI](https://github.com/conda-forge/pandas-feedstock/pulls)
376+
- Access to the social media accounts, to publish the announcements.
377+
378+
Pre-release
379+
```````````
380+
381+
1. Agree with the core team on the next topics:
382+
383+
- Release date (major/minor releases happen usually every 6 months, and patch releases
384+
monthly until x.x.5, just before the next major/minor)
385+
- Blockers (issues and PRs that must be part of the release)
386+
- Next version after the one being released
387+
388+
2. Update and clean release notes for the version to be released, including:
389+
390+
- Set the final date of the release
391+
- Remove any unused bullet point
392+
- Make sure there are no formatting issues, typos, etc.
393+
394+
3. Make sure the CI is green for the last commit of the branch being released.
395+
396+
4. If not a release candidate, make sure all backporting pull requests to the branch
397+
being released are merged.
398+
399+
5. Create a new issue and milestone for the version after the one being released.
400+
If the release was a release candidate, we would usually want to create issues and
401+
milestones for both the next major/minor, and the next patch release. In the
402+
milestone of a patch release, we add the description ``on-merge: backport to <branch>``,
403+
so tagged PRs are automatically backported to the release branch by our bot.
404+
405+
6. Change the milestone of all issues and PRs in the milestone being released to the
406+
next milestone.
407+
408+
Release
409+
```````
410+
411+
1. Create an empty commit and a tag in the last commit of the branch to be released:
412+
413+
git checkout <branch>
414+
git pull --ff-only upstream <branch>
415+
git clean -xdf
416+
git commit --allow-empty --author="Pandas Development Team <[email protected]>" -m "RLS: <version>"
417+
git tag -a v<version> -m "Version <version>" # NOTE that the tag is v1.5.2 with "v" not 1.5.2
418+
git push upstream <branch> --follow-tags
419+
420+
The docs for the new version will be built and published automatically with the docs job in the CI,
421+
which will be triggered when the tag is pushed.
422+
423+
2. Only if the release is a release candidate, we want to create a new branch for it, immediately
424+
after creating the tag. For example, if we are releasing pandas 1.4.0rc0, we would like to
425+
create the branch 1.4.x to backport commits to the 1.4 versions. As well as create a tag to
426+
mark the start of the development of 1.5.0 (assuming it is the next version):
427+
428+
git checkout -b 1.4.x
429+
git push upstream 1.4.x
430+
git checkout main
431+
git commit --allow-empty -m "Start 1.5.0"
432+
git tag -a v1.5.0.dev0 -m "DEV: Start 1.5.0"
433+
git push upstream main --follow-tags
434+
435+
3. Build the source distribution (git must be in the tag commit):
436+
437+
./setup.py sdist --formats=gztar --quiet
438+
439+
4. Create a [new GitHub release](https://github.com/pandas-dev/pandas/releases/new):
440+
441+
- Title: ``Pandas <version>``
442+
- Tag: ``<version>``
443+
- Files: ``pandas-<version>.tar.gz`` source distribution just generated
444+
- Description: Copy the description of the last release of the same kind (release candidate, major/minor or patch release)
445+
- Set as a pre-release: Only check for a release candidate
446+
- Set as the latest release: Leave checked, unless releasing a patch release for an older version
447+
(e.g. releasing 1.4.5 after 1.5 has been released)
448+
449+
5. The GitHub release will after some hours trigger an
450+
[automated conda-forge PR](https://github.com/conda-forge/pandas-feedstock/pulls).
451+
Merge it once the CI is green, and it will generate the conda-forge packages.
452+
453+
6. Packages for supported versions in PyPI are built in the
454+
[MacPython repo](https://github.com/MacPython/pandas-wheels).
455+
Open a PR updating the build commit to the released version, and merge it once the
456+
CI is green.
457+
458+
git checkout master
459+
git pull --ff-only upstream master
460+
git checkout -B RLS-<version>
461+
sed -i 's/BUILD_COMMIT: "v.*/BUILD_COMMIT: "'<version>'"/' azure/windows.yml azure/posix.yml
462+
sed -i 's/BUILD_COMMIT="v.*/BUILD_COMMIT="'<version>'"/' .travis.yml
463+
git commit -am "RLS <version>"
464+
git push -u origin RLS-<version>
465+
466+
7. Download all wheels from the Anaconda repository where MacPython uploads them:
467+
https://anaconda.org/multibuild-wheels-staging/pandas/files?version=<version>
468+
to the ``dist/`` directory in the local pandas copy.
469+
470+
8. Upload wheels to PyPI:
471+
472+
twine upload pandas/dist/pandas-<version>*.{whl,tar.gz} --skip-existing
473+
474+
Post-Release
475+
````````````
476+
477+
1. Close the milestone and the issue for the released version.
478+
479+
2. Create a new issue for the next release, with the estimated date or release.
480+
481+
3. Open a PR with the placeholder for the release notes of the next version. See
482+
for example [the PR for 1.5.3](https://github.com/pandas-dev/pandas/pull/49843/files).
483+
484+
4. Announce the new release in the official channels (use previous announcements
485+
for reference):
486+
487+
- The pandas-dev and pydata mailing lists
488+
- Twitter, Mastodon and Telegram
489+
349490

350491
.. _governance documents: https://github.com/pandas-dev/pandas-governance
351492
.. _list of permissions: https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization

0 commit comments

Comments
 (0)