📝 Write a proper README by LuShadowX · Pull Request #57 · sanitizers/patchback-github-app · GitHub

The README was just the repo name, so everything about the bot — how to trigger it, what the config keys do, what permissions an installation needs — was only discoverable by reading the source.

This documents:

usage: backport-<branch> labels, both trigger orderings, and the resulting branch/title/description shapes;
the three .github/patchback.yml keys, with the real target_branch_prefix and space-delimited-label examples from cheroot and pytest;
the App permissions listed in [TODO] Document what privileges a GitHub App needs to fully function #10, noting that Checks is optional and that missing Contents/Workflows shows up as a push failure;
the failure modes and what the bot reports for each;
running an own instance, from .env.example.

Happy to trim or restructure anything that does not match how you would like it framed.

Closes #10.

Closes #10.

FTR, in the context of that issue, I was thinking about having a manifest file of the same format Probot supports, like:
https://github.com/probot/create-probot-app/blob/cbd939e480599c41800813a6996ba69cda20676e/templates/basic-js/app.yml#L4. Not just plain text explanation in readme.

Thanks for starting this. I'll probably leave a few rounds of notes before this can be merged. It'll include clarifications regarding projects where the bot is in active use, the style of links, some banners/badges, mention of the inspiration/history (CPython's backporting bot browntruck/cherry-picker). I cannot share all this right now but you could try coming up with the permission manifest file I mentioned in the previous comment meanwhile (that probably deserves a dedicated PR).

Understood on both counts — I'll wait for your notes here rather than guessing at the history and the in-use projects.

The manifest is up as #59, derived from the handlers and API calls rather than from the settings page (it matches the list in #10). Happy to drop the permissions table from this README once that lands, or keep it as prose alongside the manifest — whichever you prefer.

Added, minus the tox-dev one. The pre-commit.ci badge and results link point at this repo's master — both URLs resolve already, though the badge only goes green once #60 lands the config it reports on. I kept your convention of wrapping a link definition onto a second line only where it would otherwise run long, so the short ones stay inline.

Still holding off on the in-use projects and the browntruck/cherry-picker history until your notes.

We could probably use GFM admonitions instead of blockquotes. Although, I'm not entirely sure how to summarize what the bot does.

Also, this isn't quite exactly what the bot does. It attempts to send PRs w/ best-effort cherry-picks but sometimes fails. Sometimes, it's because of the conflicts in the patches, sometimes it's because of various external circumstances (when GitHub's drunk and there's no persistence to retry after a sufficiently long delay of hours or even days; also sometimes GH fails to deliver webhooks, and we never know of triggers).

Saying that the robot makes sure that the bugfixes are there makes it sound like it double-checks after a while that the backport PRs have been created (by this bot or manually), which it doesn't. There's a tracking issue to think consider doing that and remove the backport request label once the PR exists: #12. And I've been thinking of implementing other things that https://github.com/python/miss-islington does like linking all the backport PRs from the original PR body.

We need to mention miss-islington and cherry-picker being the inspiration for patchback. But because that solution uses a machine account and is tightly coupled with CPython, and I wanted something scalable for more ecosystems based on GitHub Apps, I started working on octomachinery and patchback + chronongrapher for projects I've been looking after and contributing to.

I'd like to highlight these users/orgs by their sponsors URLs. Plz compose detached refs in the following format
[@org_or_username]: https://github.com/sponsors/org_or_username
(it's okay if they don't have sponsors now, GH will redirect).

pytest-dev
theforeman
ogajduse
fao89
pulp
ansible-community
cherrypy
ansible
aio-libs
ansible-collections
webknjaz
sanitizers

I'm not sure this should be advertised as obviously. I'd rather not have an uncontrolled load of the app installs by random people on the internet just because they saw a link somewhere. It was originally meant to be for a tight circle of people since I never wanted to be running a high-load deployment.

This looks a little repetitive. Both show the same information (defaults). Perhaps collapse into just YAML w/ code comments. I'd also like to have --- and ... markers for aesthetics in this example.

All five addressed in 0081a31. Point by point, since a couple involved a judgement call:

Admonitions and what the bot actually does. The tagline blockquote is gone. The summary now says the bot attempts the backport, with a [!NOTE] listing the three ways it comes up short: patch conflicts, GitHub having a bad day with nothing persisted to retry from however many hours or days pass, and webhooks that never arrive so the bot never learns there was work. I also dropped the "makes sure you have bugfixes" framing entirely and said outright that it does not come back later to confirm a backport exists, by bot or by hand, with #12 referenced for the label cleanup.

Prior art. New short section crediting cherry-picker and miss-islington, then why this exists anyway: those run on a machine account and are coupled to CPython, so they don't travel, and wanting the same thing at ecosystem scale is where octomachinery came from, and with it patchback and chronographer. I put it above Usage on the theory that it explains why the thing exists — say the word if you'd rather it sat at the bottom.

Sponsors refs. Done, your twelve in your order, all as [@name]: https://github.com/sponsors/name. All twelve resolve 200 right now, so no redirects needed yet.

Not advertising installs. The ## Installation section and both github.com/apps/patchback links are gone. In their place an [!IMPORTANT] saying the deployment is small and hobby-scale, was meant for a limited circle rather than signups at scale, and to talk to you before pointing it at a new org — with self-hosting named as the option that always works. There is now no install link anywhere in the file. If that's further than you meant, the middle ground is a link plus the caveat.

Configuration. Table dropped, its content folded into the YAML as comments, so the defaults are stated once. ---/... added — and to the other two YAML examples as well, since leaving them off would have looked inconsistent.

Not touched, still waiting on you: whether the in-use list above is right, and anything else you want said about the history.

Closes sanitizers#10.

Taken from tox-pre-commit, minus the tox-dev badge, with the pre-commit.ci links pointed at this repo's `master`. The link definitions are wrapped onto a second line only where they would otherwise run long, matching the source.

* Replace the tagline blockquote with GFM admonitions. * Describe the backports as best-effort, and spell out the ways an attempt can fail: patch conflicts, GitHub flakiness with nothing persisted to retry from, and undelivered webhooks. Drop the implication that the bot verifies backports exist afterwards, pointing at sanitizers#12 for the label cleanup idea instead. * Credit cherry-picker and miss-islington as the prior art, and explain why a GitHub App was built instead: those are coupled to CPython and run on a machine account, so octomachinery, patchback and chronographer came out of wanting the same thing at ecosystem scale. * Highlight the users and orgs by their sponsors URLs. * Stop advertising the hosted App for installation, and say plainly that it is hobby-scale and not looking for signups at scale. * Collapse the settings table into the YAML example it duplicated, using code comments, and give every YAML example `---`/`...` markers.

I'm not sure if we should replace the project name with the deployment name. These are different things and this hasn't been discussed really.

Reverted — the title is patchback-github-app again. I added one sentence under it drawing the line explicitly: the project is patchback-github-app, the App it registers as (hosted or self-run) is Patchback, and the rest of the file uses Patchback for the App. That way nothing is renamed by this PR and the distinction is at least stated. If you want a different title, or the body switched over to "the App" throughout, that is a call for you.

This is short enough to keep on the same line

Suggested change

      
            [GH Sponsors URL]:
          
            https://github.com/sponsors/webknjaz
          
            [GH Sponsors URL]: https://github.com/sponsors/webknjaz

Applied. The other refs stay wrapped only because their URLs do not fit — the badge one is 118 characters on its own.

This isn't really/fully accurate. cherry-picker is a CLI app that miss-islington effectively imports they are tightly coupled and are sort of one thing, except the former is mainly only used by the contributors to CPython (and a few other projects that configured it like aiohttp and Ansible) in local dev/contrib envs, while the latter is a web service (authenticating with a machine account, unlike the CLI which uses whatever's in the env) specifically configured for the python/cpython repository and nothing else (it wraps python/cherry_picker internally).

In the case of Patchback, we only have a GitHub App (backed by a web service) and that's it. The UI is GH+configs+labels in repos. There's no CLI, but I was thinking of maybe having one at some point. So it's a bit inverse in terms of the contributor UX. Patchback has tmpdir worktrees for isolating the cherry-picking process (I originally wanted to try using pygit2 instead of Git CLI and do this all in-memory, but that library was lacking platform support at the time, so it remained in wishlist — I think it'll be interesting to also plug it into cherry-picker if it works out later).

Thanks — rewritten in fb0b92e. cherry-picker is now described as the CLI contributors run in their own env with whatever credentials are there, miss-islington as the web service that imports it and authenticates as a machine account for python/cpython alone, so the two read as one thing rather than two parallel tools. The "coupled to CPython" framing is gone, replaced with aiohttp and Ansible having configured the CLI for local runs.

The inverse-UX point is in there too: Patchback is only ever the service half, with labels, per-repo config and the GitHub UI where cherry-picker has a command line, and a CLI is not ruled out later. Plus the throwaway worktree under a tmpdir, and pygit2 in memory as the original intent that platform support was not ready for — noted as still on the wish list for cherry-picker as much as here.

Checked the code while writing it: event_handlers.py:132 is a TemporaryDirectory with git init and --git-dir/--work-tree pointed at it, so "throwaway worktree" is literally what it is.

(trying to organize my memory)

My GitHub Apps interest came in when GH announced it around 2018 and there were no libs for it. Probot was only starting, most helpers were mainly for regular webhook handling. And Travis CI was trying out this new tech in alpha. There was nothing in Python and I wanted to have a microframework for GitHub Apps that would feel pythonic. I wanted to try out the new Checks APIs that were only available for GitHub Apps.

And so reimplementing a few checks for on the intersection of the tooling that was in use in the ecosystem seemed like a good fit. Although, a very limited number of projects have any sort of standard process referred to as “backporting”. One of the first I've been exposed to was at PortaOne over probably 15 years ago, it used Gerrit and some Git aliases or maybe pure Git commands. Later, I saw CPython and aiohttp, and then Ansible processes. They all use a mixure of sometimes (semi-)automatic and sometimes manual backporting of patches that normally need to include change log fragments. The main branch submission (PR) could often contain several commits and be merged with a natural merge commit, but the backports would always be squashed into a single combined commit.

The change log fragments are typically managed by Towncrier (which is coming from the Twisted ecosystem) which is why I've built Chronographer (inspired by https://github.com/pypa/browntruck and https://github.com/python/bedevere). Though, some ecosystems use different change log management mechanisms (CPython has its own tool blurb, together with blurb_it and bedevere; OpenStack ecosystem has reno; ansible has antsibull-changelog which is reno-based; coveragepy uses scriv). I've also built a Sphinx integration for unreleased Towncrier news files previews @ https://sphinxcontrib-towncrier.rtfd.io, so I'm pretty invested in this thing across the board.

The cherry-picking side of things comes coupled with managing the release notes because this is all a part of a good release management strategy, that's why Patchback was made almost at the same time. I've just checked and the initial commits in both of these repos are just over 20 hours apart. I think the change log automation was easier for the more traditional ecosystem, so I started there (it wasn't really doable for reno-based process in Ansible). But at some point, @felixfontein pinged me on IRC regarding backporting in the realm of Ansible Collections (I'd already integrated cherry-picker for manual runs in Ansible at the time) and I was seeing this process in multiple places + had contributed to cherry-picker refactoring around that time, so I had some ideas regarding having Patchback generally shaped similarly to Chronographer.

Written up as a ## History section in fb0b92e, at the bottom rather than up top — ## Prior art stays where it is and ends with a pointer to it, so the front of the file does not open with two pieces of backstory before Usage.

It covers: 2018, GitHub pushing Apps with the Checks API exclusive to them and Travis CI trialling the platform in alpha, nothing in Python for it, Probot only starting, so octomachinery as a Pythonic microframework — with the ecosystem-intersection checks as the way to exercise it. Then how rare a named backporting process is, PortaOne on Gerrit plus Git aliases fifteen years earlier, then CPython, aiohttp and Ansible, all mixing automatic, semi-automatic and manual, all wanting a change log fragment with the patch, and the several-commits-and-a-merge-commit versus always-squashed asymmetry. Then Towncrier out of Twisted and Chronographer managing it, inspired by browntruck and bedevere, with blurb/blurb_it, reno, antsibull-changelog and scriv as the other ecosystems' answers, and sphinxcontrib-towncrier for previews. Then the two halves of one release strategy, started within a day of each other, change log first because it was tractable for a Towncrier-shaped process and not really for a reno-based one, and Felix Fontein raising Ansible collections on IRC while you were refactoring cherry-picker as what brought backporting into focus.

Two things I checked rather than assumed:

The repos were created 20h18m apart — patchback-github-app at 2018-11-28T16:39:57Z, chronographer-github-app at 2018-11-29T12:58:16Z. So "just over 20 hours" holds, and the README says "within a day of each other".
By creation date Patchback is first, which would contradict starting with the change log side — except Chronographer's earliest commit is dated 2018-05-27, six months before either repo existed. So the change log work does come first and I wrote it that way.

Tell me if anything is off, particularly PortaOne and the reno point — those are the two I could not check anywhere.

Keep the project name in the title, fix how cherry-picker and miss-islington relate, and write up where the App came from.

It's probably not a good idea to put me on the spot in the readme wrt the deployment

Haha, sorry about that. I've seen many projects where the README says to ping the developer if there's an issue, so I assumed it was okay.

It's more of a repo name. I still think of the project name as Patchback (it's the Python importable/entrypoint/etc) and it's also the name as the main GitHub App deployment. It just happens that I don't run any other deployments, so there's no other names and this name can confusingly mean the project, the repo, the deployment and whatever unexplained thing an arbitrary GH user could think of. When I mentioned reverting the README title, I was mostly just talking about not being sure what the title of the document should be, nothing beyond that.

Honestly, I'm still not sure what this document should contain. I'm used to projects having a separate docs website. A Sphinx-based one. It'd be in a separate folder and published on RTD. The readme would be mostly about the code/project, but some website sections could mention the deployment too.

Maybe, we need to have a separate discussion about what kinds of docs are needed on the high level first. We can still keep collecting the info / capture memories here, but I wouldn't expect this to be merged soon as it's not clear where the scope of this PR ends.

let's pick this into a separate PR for now

And this too

plus maybe this

Removes the `ping @webknjaz` line per review, and extracts the Contributing and License sections into their own pull requests so what is left here is just the Patchback narrative.

Split done in 58999d0. The ping @webknjaz line is gone, and the two boilerplate sections are now their own PRs: #62 (License) and #63 (Contributing). They touch the same readme region, so the second to land needs a trivial rebase.

I left the intro paragraph and the project-vs-App naming note here rather than splitting them too — those are the parts your scope question is actually about, so they should follow whatever you decide about the docs layout, not land ahead of it.

Agreed on parking this one. If you want to open that high-level discussion about what docs belong where — readme vs a Sphinx site on RTD — I'm happy to keep adding to this branch as a scratchpad in the meantime, with no expectation of it merging as-is.

@LuShadowX could you move the badges into a separate PR?

Done — the banner and badges are out of this branch in 7ef8b56 and up as #67.

This branch still needs a rebase; I left it alone since the scope here is still open. Happy to do it whenever it is going anywhere.

I've merged those PRs, rebasing can make the diff here smaller.

@LuShadowX rebase?

LuShadowX mentioned this pull request Jul 27, 2026

🐛 Don't render None as the backport PR body #58

Merged

LuShadowX mentioned this pull request Jul 27, 2026

🔧 Add a GitHub App manifest with the needed privileges #59

Merged

webknjaz reviewed Jul 27, 2026

View reviewed changes

Comment thread README.md Outdated

LuShadowX mentioned this pull request Jul 27, 2026

🔧 Add a pre-commit config with hygiene checks #60

Merged

webknjaz reviewed Jul 27, 2026

View reviewed changes

LuShadowX and others added 3 commits July 28, 2026 11:42

📝 Write a proper README

c49cd28

Closes sanitizers#10.

📝 Add the standard banners and badges

495ea83

Taken from tox-pre-commit, minus the tox-dev badge, with the pre-commit.ci links pointed at this repo's `master`. The link definitions are wrapped onto a second line only where they would otherwise run long, matching the source.

LuShadowX force-pushed the readme branch from 0081a31 to 75924fc Compare July 28, 2026 06:12

webknjaz reviewed Jul 28, 2026

View reviewed changes

📝 Correct the prior art and record the history

fb0b92e

Keep the project name in the title, fix how cherry-picker and miss-islington relate, and write up where the App came from.

webknjaz reviewed Jul 31, 2026

View reviewed changes

📝 Drop the maintainer ping and split out the boilerplate

58999d0

Removes the `ping @webknjaz` line per review, and extracts the Contributing and License sections into their own pull requests so what is left here is just the Patchback narrative.

This was referenced Aug 1, 2026

📝 State the license in the readme #62

Merged

📝 Point the readme at the issue tracker #63

Merged

LuShadowX mentioned this pull request Aug 15, 2026

📝 Add the banner and badges to the readme #67

Merged

📝 Split the banners and badges out of the readme PR

7ef8b56

+              ```yaml
+              backport_branch_prefix: patchback/backports/
+              backport_label_prefix: backport-
+              target_branch_prefix: ''
+              ```
+              | Setting | Default | Meaning |
+              | --- | --- | --- |
+              | `backport_branch_prefix` | `patchback/backports/` | Prefix of the branches the bot pushes. |
+              | `backport_label_prefix` | `backport-` | Labels carrying this prefix trigger a backport. |
+              | `target_branch_prefix` | *(empty)* | Prepended to the rest of the label to compute the target branch. |

+              run under a machine account and are tightly coupled to CPython, so they
+              do not travel to other projects. Wanting that same convenience at
+              ecosystem scale, [@webknjaz] built this one on GitHub Apps instead —
+              which is where [octomachinery] came from, and with it Patchback and

+              [![SWUbanner]][SWUdocs]
+              [![pre-commit.ci status badge]][pre-commit.ci results page]
+              [![GH Sponsors badge]][GH Sponsors URL]
+              [SWUbanner]:
+              https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-single.svg
+              [SWUdocs]:
+              https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md
+              [pre-commit.ci status badge]:
+              https://results.pre-commit.ci/badge/github/sanitizers/patchback-github-app/master.svg
+              [pre-commit.ci results page]:
+              https://results.pre-commit.ci/latest/github/sanitizers/patchback-github-app/master
+              [GH Sponsors badge]:
+              https://img.shields.io/badge/%40webknjaz-transparent?logo=githubsponsors&logoColor=%23EA4AAA&label=Sponsor&color=2a313c
+              [GH Sponsors URL]: https://github.com/sponsors/webknjaz
               # patchback-github-app
+              This is the GitHub App that cherry-picks merged pull requests into your
+              maintenance branches. You label a pull request, it gets merged, and the
+              bot attempts the corresponding backport PR — no manual `git cherry-pick`
+              juggling.


		# Patchback

		> Backporter robot making sure you have bugfixes in old versions.

+              [aiohttp]: https://github.com/aio-libs/aiohttp
+              [pytest]: https://github.com/pytest-dev/pytest
+              [cheroot]: https://github.com/cherrypy/cheroot

+              ## Installation
+              Install the App from https://github.com/apps/patchback and grant it
+              access to the repositories you want backports in. See

	[GH Sponsors URL]:
	https://github.com/sponsors/webknjaz
	[GH Sponsors URL]: https://github.com/sponsors/webknjaz

		Patchback follows CPython's [cherry-picker] and [miss-islington]. Both
		run under a machine account and are tightly coupled to CPython, so they

+              Bug reports and pull requests are welcome at
+              https://github.com/sanitizers/patchback-github-app.
+              If you think the deployed bot is misbehaving, ping `@webknjaz`.

+              ## License
+              Patchback is distributed under the terms of the
+              [GNU General Public License v3.0](LICENSE).

		@@ -1 +1,269 @@
		# patchback-github-app

📝 Write a proper README by LuShadowX · Pull Request #57 · sanitizers/patchback-github-app · GitHub

Uh oh!

Uh oh!

📝 Write a proper README - #57

📝 Write a proper README#57LuShadowX wants to merge 6 commits intosanitizers:mastersanitizers/patchback-github-app:masterfrom LuShadowX:readmeLuShadowX/patchback-github-app:readmeCopy head branch name to clipboard

Conversation

LuShadowX commented Jul 27, 2026

Uh oh!

webknjaz commented Jul 27, 2026

Uh oh!

webknjaz commented Jul 27, 2026

Uh oh!

LuShadowX commented Jul 27, 2026

Uh oh!

Uh oh!

LuShadowX commented Jul 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LuShadowX commented Jul 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LuShadowX commented Aug 1, 2026

Uh oh!

webknjaz commented Aug 14, 2026

Uh oh!

LuShadowX commented Aug 15, 2026

Uh oh!

webknjaz commented Aug 15, 2026

Uh oh!

webknjaz commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

📝 Write a proper README#57
LuShadowX wants to merge 6 commits into
sanitizers:masterfrom
LuShadowX:readme