hello patchette
commit 3027acaff3274da9843d5cf0b96094000d81b5e8
· browse this tree
warpfork, 2026-10-17 21:32:35 UTC
diff --git a/README.md b/README.md new file mode 100644 index 0000000..90239fb --- /dev/null +++ b/README.md @@ -0,0 +1,243 @@ +Patchette +======= + +Patchette is a tool for managing patches. + + +Wot? +---- + +Patches. To software. Patchette manages them. + +What do we mean by "patches"? + +- Well, actually, git commits, in practice. +- (But we're going to store them as patch files, instead of directly in a repo. For reasons. Keep reading.) + +What do we mean by "manage"? + +- We want to *store* the patches. +- We want to help *update* them... + - either because the upstream has changes and the patches need to change as a result too, + - or because the development work continues +- And most of all we want that to result in the ability + to ***track the evolution of the patches*** over time. + +Some existing and familiar tooling already does a decent job at some of those things -- +indeed, git and git-rebase are already fundamentally storing patches and helping update them! -- +but things don't handle that last bit: tracking the evolution. + + +The Bigger Picture +------------------ + +Software is developed in "repos" and there's often +an "upstream" (where publication is Someone Else), +and then work is done in our personal "forks" or "clones". + +Sometimes our clones of a repo diverge briefly: +we make a change, commit it in our clone, +offer it to the upstream (whether by "push" or by email attachment or anything in between), +and then if all is good and cool, upstream accepts it as-is. + +Patchette generally isn't relevant, then. + +But that's the "happy path". That's... not usually how things go. + +Sometimes it's a longer-term situationship. + +### relationships to upstreams + +"The upstream" in software can be a term that's loaded with a lot of diplomatic nuance. +Patchette doesn't have any opinion about that, of course (how could we?), +but we would say that there's roughly three kinds of practical relationships +that a set of patches can have vs an upstream: + +- patching locally, with NO intent to upstream ("malleable software"); +- patching locally, WITH intent to upstream + (but even with intent to upstream, there's always the implicit reality that it's gonna take a bit, + and so we might want to track changes-to-the-changes during that period); +- or, no longer patching, but still want to have an archival record + of the previously used patches available for historical reference. + +The observation that Patchette is based on is that in all three of these stories, +there can be a substantial *passage of time*, +and during which your patches may *evolve* (or even be dropped)... + +And if you aren't tracking the changes to your patches, +then every "evolve" is actually a loss of information. + +(And we think that's bad.) + +### changes to changes are meaningful + +When patches change, that's often worth tracking. + +- Did upstream fix something? (Or partially fix something? Or maybe break something else?) + The patch repo is a place to observe it and to chronicle it. +- Did a patch get *simpler* because of a partial fix? Or more complicated? + The patch repo is a place to observe it and to chronicle it. +- Did a patch remain needed, but just *move*? + The patch repo is a place to observe it, etc. + +Maybe some of these things make your own private development processes +go easier and more sure-footedly forward. +Maybe some of the reviewability this gives you can actuall turn into +good information to talk with the upstream about, for mutual benefit. +You'll never know until you start *having* the information to work with. + + +Patchette's Solution +------------------ + +tl;dr: + +- the main/subject repo stays totally normal. +- Patchette makes a separate repo for patches. +- When you track a branch from the main/subject repo with Patchette: + - the branch gets mapped into a folder in the patches repo, + - and every commit gets mapped to a file in that folder, + - and a little metadata file describes where the patches were meant to apply. + +And that's it. +But that little bit of information enables a lot of things. + +### your development workflow + +... doesn't have to change. + +Actual development still happens in the subject repo. +You still use git branches. +Normal git tools like rebase still get to do their work; +any workflow you have using it still applies, entirely. + +Every time you run Patchette, +it'll just update the patches repo with a snapshot of all +the branches that you told Patchette to track. + +It's purely value-add. + +Patchette doesn't demand any particular structure of your commits, nor insert anything into them, either. +If you someday take the patches you've managed with Patchette and decide you actually do want to upstream them, +then you just... take the branch, and push it. Nothing special. No fanfare needed. +Patchette never put anything into your commits that you'd need or want to redact. +They're just... your commits. + +### you get to see the changes to the changes + +The patches repo is something you can now use regular "git diff" on. + +### you can describe the changes to the changes in the patches repo commit messages + +... if you want. + +Or make all your patches repo commit messages "asdf". I'm not your boss. + +### you can recreate the branches from the patches + +If you have a patches repo, +you can then delete the subject repo entirely, +clone it again from upstream (who's not carrying any of your patches or branches!), +and then use Patchette to recreate branches exactly like you had them before, +just from what's saved in the patches repo. + +Is this any easier than just keeping the full clone around, with your branches in it? +Eh, it depends. Maybe not! But maybe yes: + +- If the full clone is huge and you don't wanna keep it on hand all the time, then this capability can be handy! +- It does most certainly mean you can push the patches repo somewhere, and *it's* small! +- Operationally, it's easy to describe "repo XYZ is a mirror from a remote" and "repo XYZ-patches is authoritative". + +### do any of these things matter? + +lol, well. YMMV. But IYKYK. + +(Your mileage may vary. But if you know, you know.) + +*Sometimes*. + +Sometimes the evolution to your patches will be trivial. +Sometimes you'll do some updates and "rebased on upstream main" is all the more description you really need. +Often, even. + +But then there's The Other Times. + +There's times where upstreaming something takes weeks, or months, +and dozens of rounds of changes. + +There's times where you're doing the "malleable software" thing, +and you're *not* upstreaming things *on purpose*, +so you're carrying patches for months or for years, while the upstream keeps evolving. + +In those cases? Yeah. +You're probably going to want to start reviewing the changes-to-the-changes sometimes. +You're probably going to want to start leaving comments on *how* and *why* your +patches had to adapt around upstream changes. + +That's when you're going to start being happy you have Patchette to help with that. + +### really? another repo? + +Yep. + +It makes sense for logical isolation. + +But also it's very practical, in that +*the patch repo doesn't grow any faster than your actual patches and changes to them do.* + +#### does Patchette *have* to operate a *whole repo* all by itself? + +Nah. It's a default behavior. + +But if you want to keep your patches in a repo that's also used for other stuff? + +(Like, let's say similar to the way Arch does packaging repos? mhmm?) + +Yeah, sure. Totally fine. Go for it. + + +Y u no... +---------- + +### y u no just git rebase + +Git's rebase flow is a well known answer for +how to keep some changes up to date with an upstream. +And git itself effectively can be said to just store a series of patches. +(I mean, it's not implemented like that, internally, but, +semantically, we could *say* it works *like* that.) + +That's cool, but Patchette is for when you need more. +Patchette is for when you want to track changes *to the changes*. + +Git rebase immediately forgets the previous diffs if it succeeds. +This is true no matter how massively you may have rewritten them during the rebase. +(Yes, there's a thing called the git-reflog, too. +But that's temporary. And more for "oh shit"-undo reactions than meant as a tracking system.) + +*Patchette actually tracks the diffs*, +so it *can easily track and show their evolution*. + +Patchette still actually lets you *use* git-rebase for evolving the changes. +Git rebase is just fine at that! We don't have any reason to reinvent *that* wheel. +Patchette is just for *the rest* of what we want. + +### y u no use mercurial!!! + +Yeah, mercurial had a feature for tracking evolution of changes like this, didn't it. + +Huh. Weird. Hey, ya'll think maybe... mercurial had some good ideas? Hm! + + +License +------- + +If I've really got to pick? Fine. + +SPDX-License-Identifier: Apache-2.0 OR MIT + +Or? + +BSD0. + +I really don't care anymore. Use it and be free.