git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: "brian m. carlson" <sandals@crustytoothpaste.net>
To: <git@vger.kernel.org>
Cc: "Taylor Blau" <me@ttaylorr.com>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"Emily Shaffer" <emilyshaffer@google.com>,
	"Johannes Schindelin" <Johannes.Schindelin@gmx.de>
Subject: [RFC PATCH 1/2] doc: specify a header for including arbitrary format-patch metadata
Date: Mon, 19 Sep 2022 14:52:30 +0000	[thread overview]
Message-ID: <20220919145231.48245-2-sandals@crustytoothpaste.net> (raw)
In-Reply-To: <20220919145231.48245-1-sandals@crustytoothpaste.net>

Right now, we lack a way to specify arbitrary metadata for format-patch.
We currently special-case the base-commit value, but this is not helpful
in the general case.  There has also been interest in specifying
signatures for transport between machines using mailing list patches.

In a future commit, we will define a format for the author and committer
data such that the email represents an opaque ID instead of an email.
As a practical matter, this makes it difficult to send patches, since
many mail servers will not accept arbitrary From lines.  Even using
in-body From headers is not suitable here because we will want to
include entries in the mailmap out-of-band as part of the patch.

To make this case more general and allow us to specify this information
in a more general way, let's add a metadata header which can be included
in the patch and allow specifying arbitrary values that we can then fill
in.  We explicitly specify an extension mechanism to allow others to use
this data in a time-tested way that avoids conflicts.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 .../technical/format-patch-metadata.txt       | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 Documentation/technical/format-patch-metadata.txt

diff --git a/Documentation/technical/format-patch-metadata.txt b/Documentation/technical/format-patch-metadata.txt
new file mode 100644
index 0000000000..5448918da9
--- /dev/null
+++ b/Documentation/technical/format-patch-metadata.txt
@@ -0,0 +1,55 @@
+format-patch Metadata
+=====================
+
+Background
+----------
+
+The current format-patch data lacks a way to express general metadata that may
+be useful to synthesize the original commit more accurately.  This may be
+helpful to emit patches as a transport for actual commits between machines in a
+case where bundles are not practical, such as a mailing list.
+
+Syntax
+------
+
+The syntax contains three space-separated components: a field name, an encoding,
+and field data.
+
+The field name contains no spaces.  Values without an `@` are specified below or
+by a future version of Git.  Values containing an `@` followed by a domain are
+specified by that domain owner, much as algorithm names in the SSH protocol.
+
+The encoding is either `plain`, in which case the field data is a literal string
+with no spaces, or `base64`, in which case the field data is one or more
+space-separated base64 items, which when interpreted have all spaces stripped
+and are then encoded.  This allows fields to be specified that contain octets
+which are not valid in or which are too long to specified in an RFC 5322 header
+unencoded.
+
+Fields
+------
+
+base-commit-sha1::
+	This specifies the base commit for this patch using a SHA-1 object ID.
+base-commit-sha256::
+	This specifies the base commit for this patch using a SHA-256 object ID.
+	appropriate.
+gpgsig-sha1::
+	This specifies a signature for this patch using the SHA-1 format, as specified
+	in the `gpgsig` header.
+gpgsig-sha256::
+	This specifies the base commit for this patch using the SHA-256 object ID, as
+	specified in the `gpgsig-sha256` header.
+
+Examples
+--------
+
+----
+X-Git-Metadata: base-commit-sha1 plain da39a3ee5e6b4b0d3255bfef95601890afd80709
+
+X-Git-Metadata: gpgsig-sha256 base64
+  LS0tLS1CRUdJTiBTU0ggU0lHTkFUVVJFLS0tLS0KYmxhaCBibGFoIGJsYWgKLS0tLS1FTkQgU1NI
+  IFNJR05BVFVSRS0tLS0tCg==
+
+X-Git-Metadata: foo@example.com plain quux
+----

  reply	other threads:[~2022-09-19 15:00 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-09-19 14:52 [RFC PATCH 0/2] Opaque author and committer identifiers brian m. carlson
2022-09-19 14:52 ` brian m. carlson [this message]
2022-09-19 14:52 ` [RFC PATCH 2/2] docs: document a format for anonymous author and committer IDs brian m. carlson
2022-09-20 10:51   ` Ævar Arnfjörð Bjarmason
2022-09-22  0:08     ` brian m. carlson
2022-09-30 20:26   ` Gwyneth Morgan
2022-10-02  0:27     ` brian m. carlson

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220919145231.48245-2-sandals@crustytoothpaste.net \
    --to=sandals@crustytoothpaste.net \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=avarab@gmail.com \
    --cc=emilyshaffer@google.com \
    --cc=git@vger.kernel.org \
    --cc=me@ttaylorr.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).