Representing a single proposed patch

I thought I had this figured out. Nope, I spent hours staring at the screen and reading manpages and web search results. And still not sure what’s the best way to go. I have a proposal but I’d like to have some feedback before I implement it.

The Previous Situation

Until now the idea was that a patch would be an object of type Patch and its content would be the actual patch diff, in whatever the VCS-specific format is. Git sends each patch as a separate email message, so I thought, let’s do the same in ForgeFed, each Patch’s content being the email-like patch that git format-patch produces. Darcs on the other hand produces a single “patch bundle” file, containing multiple new patches, their context (i.e. info of existing patches they depend on) and a hash of the entire bundle. So, I thought, let’s just have the Patch content contain that entire bundle. Simple.

This approach did have a problem: The patch author, time, etc. info is included twice: Once in the AP representation (via attributedTo, published, etc.) and again inside the patch file itself (committer name, email, timestamp, etc.). But I thought, not a big issue, just verify the data matches.

A patch object could look like this:

{ "id": "https://dev.example/alice/merge-requests/34583485354/patches/934293",
  "type": "Patch",
  "attributedTo": "https://dev.example/alice",
  "mediaType": "application/x-darcs-patch",
  "content": "...",
  "context": "https://dev.example/alice/merge-requests/34583485354",
  "replies": "https://dev.example/alice/merge-requests/34583485354/patches/934293/replies"
}

The Problem I’m Encountering

In git, it’s possible to have multiple patches in a single file. Because each file is in mbox format. So, I could be giving git 3 files, that end up resulting with 5 emails being sent. On the other side, of course the mail server puts them together into the recipient inboxes, in whatever format is used there for storage… the point is, in transit each patch is a separate email.

It only makes sense to me, that each individual patch gets its own Patch object and can have its own set of replies, just like it’s possible in email. How VCS programs produce patch files for email is irrelevant, it’s an email specific detail. Just like each patch is a separate email, we’d want each patch to have its own Patch object. So alongside the tricks VCSs use for sending email, we need a separate mechanism for sending patches over ActivityPub. It doesn’t make sense to go through mbox or anything like that, because that’s an email format, not compatible with JSON.

New Proposal

Regardless of the VCS, each patch gets its own Patch object! The patch file itself contains just the diff, everything else is in JSON properties. This includes stuff like the “patch bundle hash” and “context” previous patch dependencies and so on. So for each VCS there’s a definition of how to represent patches in ActivityPub.

I guess this may lead us to ask: Why not represent the patch diff itself as structured JSON instead of plain text? I guess that’s possible, but idk if there’s anything to gain. And using mediaType we can always add that option without breaking stuff.

Sounds reasonable?

for git, you are considering only the git send-email format; but
that is not the only way git can handle patches - git can export
and import normal unified patch format text files too - probably
darcs can also

im pretty sure that anything, which the patch program can
process, git can process too - if some other VCS can not,
that would need an adapter to do the conversion between
forge-fed format, and something that specific VCS can handle

just as, there should be an optional email bridge which
handles mail, and converts it to and from forge-fed format -
the forge-fed mechanism in each forge, does not need to handle
emails directly - it would be the job of the email bridge to
translate to and from the forge-fed format

the forge-fed format should be totally agnostic to the VCS and
to the client (email client, command-line client, another AP
peer, etc) - there no reason why this can not be interoperable
with git-ssb in the future, if the basic design is generic enough

“one-patch-per-object” seems perfectly reasonable for v1 - that
would be useful to also support patch series, such a quilt and
darcs produce - if each patch is separate in the basic forge-fed
design, patch series could be added on trivially, just by adding
a quilt-like series file - it is just a text file with one patch
per line, describing which order to apply them - that seems
generic and capable enough as a base implementation, to support
almost anything later

stripping away the git-specific headers from a git send-email,
has the disadvantage of losing the author information; but i
would do the simpler thing first - later (v2 perhaps?), more
sophisticated handling of git send-emails and the darcs bundles
could be added as new features; but that could also be done with
plugins, if the basic design supports patch series generically