Package: cherry_picker
Usage (from a cloned CPython directory)cherry_picker [--pr-remote REMOTE] [--upstream-remote REMOTE] [--dry-run] [--config-path CONFIG-PATH] [--status] [--abort/--continue] [--push/--no-push] [--auto-pr/--no-auto-pr] <commit_sha1> <branches>ContentsAboutSetup InfoCherry-picking 🐍🍒⛏️Commit sha1OptionsDemoExample–pr-remoteoption–upstream-remoteoption–statusoption–abortoption–continueoption–no-pushoption–no-auto-proption–config-pathoptionCreating Pull RequestsRunning TestsPublishing to PyPILocal installationChangelog2.2.02.1.02.0.01.3.21.3.11.3.01.2.21.2.11.2.01.1.11.1.01.0.0AboutThis tool is used to backport CPython changes frommaininto one or more
of the maintenance branches (3.6,3.5,2.7).cherry_pickercan be configured to backport other projects with similar
workflow as CPython. See the configuration file options below for more details.The maintenance branch names should contain some sort of version number (X.Y).
For example:3.6,3.5,2.7,stable-2.6,2.5-lts, are all
supported branch names.It will prefix the commit message with the branch, e.g.[3.6], and then
opens up the pull request page.Tests are to be written usingpytest.Setup InfoRequires Python 3.8+.$python3-mvenvvenv$sourcevenv/bin/activate(venv)$python-mpipinstallcherry_pickerThe cherry picking script assumes that if anupstreamremote is defined, then
it should be used as the source of upstream changes and as the base for
cherry-pick branches. Otherwise,originis used for that purpose.
You can override this behavior with the--upstream-remoteoption
(e.g.--upstream-remotepythonto use a remote namedpython).Verify that anupstreamremote is set to the CPython repository:$gitremote-v...
upstream    https://github.com/python/cpython (fetch)
upstream    https://github.com/python/cpython (push)If needed, create theupstreamremote:$gitremoteaddupstreamhttps://github.com/python/cpython.gitBy default, the PR branches used to submit pull requests back to the main
repository are pushed toorigin. If this is incorrect, then the correct
remote will need be specified using the--pr-remoteoption (e.g.--pr-remoteprto use a remote namedpr).Cherry-picking 🐍🍒⛏️(Setup first! See prev section)From the cloned CPython directory:(venv)$cherry_picker[--pr-remoteREMOTE][--upstream-remoteREMOTE][--dry-run][--config-pathCONFIG-PATH][--abort/--continue][--status][--push/--no-push][--auto-pr/--no-auto-pr]<commit_sha1><branches>Commit sha1The commit sha1 for cherry-picking is the squashed commit that was merged to
themainbranch.  On the merged pull request, scroll to the bottom of the
page.  Find the event that says something like:<coredeveloper> merged commit <commit_sha1> into python:main <sometime> ago.By following the link to<commit_sha1>, you will get the full commit hash.
Use the full commit hash forcherry_picker.py.Options--dry-run                 Dry Run Mode.  Prints out the commands, but not executed.
--pr-remote REMOTE        Specify the git remote to push into.  Default is 'origin'.
--upstream-remote REMOTE  Specify the git remote to use for upstream branches.
                          Default is 'upstream' or 'origin' if the former doesn't exist.
--status                  Do `git status` in cpython directory.Additional options:--abort        Abort current cherry-pick and clean up branch
--continue     Continue cherry-pick, push, and clean up branch
--no-push      Changes won't be pushed to remote
--no-auto-pr   PR creation page won't be automatically opened in the web browser or
               if GH_AUTH is set, the PR won't be automatically opened through API.
--config-path  Path to config file
               (`.cherry_picker.toml` from project root by default)Configuration file example:team="aio-libs"repo="aiohttp"check_sha="f382b5ffc445e45a110734f5396728da7914aeb6"fix_commit_msg=falsedefault_branch="devel"Available config options:team            github organization or individual nick,
                e.g "aio-libs" for https://github.com/aio-libs/aiohttp
                ("python" by default)

repo            github project name,
                e.g "aiohttp" for https://github.com/aio-libs/aiohttp
                ("cpython" by default)

check_sha       A long hash for any commit from the repo,
                e.g. a sha1 hash from the very first initial commit
                ("7f777ed95a19224294949e1b4ce56bbffcb1fe9f" by default)

fix_commit_msg  Replace # with GH- in cherry-picked commit message.
                It is the default behavior for CPython because of external
                Roundup bug tracker (https://bugs.python.org) behavior:
                #xxxx should point on issue xxxx but GH-xxxx points
                on pull-request xxxx.
                For projects using GitHub Issues, this option can be disabled.

default_branch  Project's default branch name,
                e.g "devel" for https://github.com/ansible/ansible
                ("main" by default)To customize the tool for used by other project:Create a file called.cherry_picker.tomlin the project’s root
folder (alongside with.gitfolder).Addteam,repo,fix_commit_msg,check_shaanddefault_branchconfig values as described above.Usegit add .cherry_picker.toml/git committo add the config
intogit.Addcherry_pickerto development dependencies or install it
bypip install cherry_pickerNow everything is ready, usecherry_picker <commit_sha> <branch1> <branch2>for cherry-picking changes from<commit_sha>into
maintenance branches.
Branch name should contain at least major and minor version numbers
and may have some prefix or suffix.
Only the first version-like substring is matched when the version
is extracted from branch name.DemoInstallation:https://asciinema.org/a/125254Backport:https://asciinema.org/a/125256ExampleFor example, to cherry-pick6de2b7817f-some-commit-sha1-d064into3.5and3.6, run the following command from the cloned CPython
directory:(venv)$cherry_picker6de2b7817f-some-commit-sha1-d0643.53.6What this will do:(venv)$gitfetchupstream(venv)$gitcheckout-bbackport-6de2b78-3.5upstream/3.5(venv)$gitcherry-pick-x6de2b7817f-some-commit-sha1-d064(venv)$gitpushoriginbackport-6de2b78-3.5(venv)$gitcheckoutmain(venv)$gitbranch-Dbackport-6de2b78-3.5(venv)$gitcheckout-bbackport-6de2b78-3.6upstream/3.6(venv)$gitcherry-pick-x6de2b7817f-some-commit-sha1-d064(venv)$gitpushoriginbackport-6de2b78-3.6(venv)$gitcheckoutmain(venv)$gitbranch-Dbackport-6de2b78-3.6In case of merge conflicts or errors, the following message will be displayed:Failed to cherry-pick 554626ada769abf82a5dabe6966afa4265acb6a6 into 2.7 :frowning_face:
... Stopping here.

To continue and resolve the conflict:
    $ cherry_picker --status  # to find out which files need attention
    # Fix the conflict
    $ cherry_picker --status  # should now say 'all conflict fixed'
    $ cherry_picker --continue

To abort the cherry-pick and cleanup:
    $ cherry_picker --abortPassing the--dry-runoption will cause the script to print out all the
steps it would execute without actually executing any of them. For example:$cherry_picker--dry-run--pr-remotepr1e32a1be4a1705e34011770026cb64ada2d340b53.63.5Dry run requested, listing expected command sequence
fetching upstream ...
dry_run: git fetch origin
Now backporting '1e32a1be4a1705e34011770026cb64ada2d340b5' into '3.6'
dry_run: git checkout -b backport-1e32a1b-3.6 origin/3.6
dry_run: git cherry-pick -x 1e32a1be4a1705e34011770026cb64ada2d340b5
dry_run: git push pr backport-1e32a1b-3.6
dry_run: Create new PR: https://github.com/python/cpython/compare/3.6...ncoghlan:backport-1e32a1b-3.6?expand=1
dry_run: git checkout main
dry_run: git branch -D backport-1e32a1b-3.6
Now backporting '1e32a1be4a1705e34011770026cb64ada2d340b5' into '3.5'
dry_run: git checkout -b backport-1e32a1b-3.5 origin/3.5
dry_run: git cherry-pick -x 1e32a1be4a1705e34011770026cb64ada2d340b5
dry_run: git push pr backport-1e32a1b-3.5
dry_run: Create new PR: https://github.com/python/cpython/compare/3.5...ncoghlan:backport-1e32a1b-3.5?expand=1
dry_run: git checkout main
dry_run: git branch -D backport-1e32a1b-3.5–pr-remoteoptionThis will generate pull requests through a remote other thanorigin(e.g.pr)–upstream-remoteoptionThis will generate branches from a remote other thanupstream/origin(e.g.python)–statusoptionThis will dogit statusfor the CPython directory.–abortoptionCancels the current cherry-pick and cleans up the cherry-pick branch.–continueoptionContinues the current cherry-pick, commits, pushes the current branch toorigin, opens the PR page, and cleans up the branch.–no-pushoptionChanges won’t be pushed to remote.  This allows you to test and make additional
changes.  Once you’re satisfied with local changes, use--continueto complete
the backport, or--abortto cancel and clean up the branch.  You can also
cherry-pick additional commits, by:$gitcherry-pick-x<commit_sha1>–no-auto-proptionPR creation page won’t be automatically opened in the web browser or
if GH_AUTH is set, the PR won’t be automatically opened through API.
This can be useful if your terminal is not capable of opening a useful web browser,
or if you use cherry-picker with a different Git hosting than GitHub.–config-pathoptionAllows to override default config file path
(<PROJ-ROOT>/.cherry_picker.toml) with a custom one. This allows cherry_picker
to backport projects other than CPython.Creating Pull RequestsWhen a cherry-pick was applied successfully, this script will open up a browser
tab that points to the pull request creation page.The url of the pull request page looks similar to the following:https://github.com/python/cpython/compare/3.5...<username>:backport-6de2b78-3.5?expand=1Press theCreate Pull Requestbutton.Bedevere will then remove theneeds backport to ...label from the original
pull request againstmain.Running TestsInstall pytest:pip install-Upytest$pytestTests require your local version ofgitto be2.28.0+.Publishing to PyPICreate a new release branch.Update the version info in__init__.pyandreadme.rst, dropping the.dev.Tag the branch ascherry-picker-vX.Y.Z.Local installationWithflitinstalled,
in the directory wherepyproject.tomlexists:$flitinstallChangelog2.2.0Add log messagesFix for conflict handling, get the state correctly. (PR 88)Drop support for Python 3.7 (PR 90)2.1.0Mix fixes: #28, #29, #31, #32, #33, #34, #36.2.0.0Support themainbranch by default. (PR 23)
To use a different default branch, please configure it in the.cherry-picker.tomlfile.Renamedcherry-picker’s own default branch tomain.1.3.2Use--no-tagsoption when fetching upstream. (PR 319)1.3.1Modernize cherry_picker’s pyproject.toml file. (PR #316)Remove theBACKPORT_COMPLETEstate. Unset the states when backport is completed.
(PR #315)Run Travis CI test on Windows (PR #311).1.3.0Implement state machine and storing reference to the config
used at the beginning of the backport process using commit sha
and a repo-local Git config.
(PR #295).1.2.2Relaxed click dependency (PR #302).1.2.1Validate the branch name to operate on with--continueand fail early if the branch could not
have been created by cherry_picker. (PR #266).Bugfix: Allow--continueto support version branches that have dashes in them.  This is
a bugfix of the additional branch versioning schemes introduced in 1.2.0.
(PR #265).Bugfix: Be explicit about the branch name on the remote to push the cherry pick to.  This allows
cherry_picker to work correctly when the user has a git push strategy other than the default
configured. (PR #264).1.2.0Adddefault_branchconfiguration item. The default ismaster, which
is the default branch for CPython. It can be configured to other branches like,devel, ordevelop.  The default branch is the branch cherry_picker
will return to after backporting. (PR #254andIssue #250).Support additional branch versioning schemes, such assomething-X.Y,
orX.Y-somethingelse. (PR #253andIssue #251).1.1.1Change the calls tosubprocessto use lists instead of strings. This fixes
the bug that affects users in Windows. (PR #238).1.1.0Addfix_commit_msgconfiguration item. Setting fix_commit_msg totruewill replace the issue number in the commit message, from#toGH-.
This is the default behavior for CPython. Other projects can opt out by
setting it tofalse. (PR #233andaiohttp Issue #2853).1.0.0Support configuration file by using--config-pathoption, or by adding.cherry-picker.tomlfile to the root of the project. (Issue #225).