While I do like the patch format, I think it has some things (really one that I can think of at this time) that wouldn’t be very conducive for email-exchanged patches (e.g. the workflow that would be used on a prospective pj.sr.ht).

My main concern is really the fact that there is no place to put “commentary” (as it’s commonly referred to when using git) – stuff that isn’t suitable for the change’s description, but e.g. to communicate what has changed since the last version. For those unfamiliar (I’d imagine that’s not many, but just to be safe), you can put such commentary below a marker line, ---, after which the diff’s contents follow.

An idea to resolve this (or, at the very least, resolve my above concern) would be for the ability to have commentary precede the patch’s contents. Something like the following:

Here is some timely commentary. In this version of the patch, I changed foo to
bar and created a wrapper type, Qux, around Baz to shorten typing in all
the places it is used. PTAL.

---

message = 'Introduce Qux as a wrapper type'
timestamp = '2020-11-23T03:19:46.908209786Z'

[[authors]]
# No `name =` since that is really only relevant for the Nest. As such, it
# really should be optional... In this example, we assume it is.
full_name = 'Cole Helbling'
email = 'cole@***.com'

# Dependencies
[2] SOMEDEPENDENCY

# Changes
# ....

For this to work as expected, it should be possible to pijul apply < file.pijul, with the above contents, and pijul should know to ignore everything before the ---.

Am I understanding this correctly that the difference between “commentary” and the description of a patch is that the latter is something that pijul cares about, whereas the former just gets ignored outright?

It’s unlikely we’re changing the format at this point, I believe it is email-friendly though.