[PATCH libgpg-error] doc: clarify patch submission workflow

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

[PATCH libgpg-error] doc: clarify patch submission workflow

Thorsten Behrens
Signed-off-by: Thorsten Behrens <[hidden email]>
---
 doc/HACKING | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/doc/HACKING b/doc/HACKING
index e30b2f8..d379099 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -2,6 +2,11 @@
 #+TITLE: Various hacking notes
 #+STARTUP: showall
 
+* How to contribute
+
+  The following stuff explains some basic procedures you need to
+  follow if you want to contribute code or documentation.
+
 * No more ChangeLog files
 
   Do not modify any of the ChangeLog files in Libgpg-error.  Starting
@@ -23,3 +28,48 @@
   in a "real" ChangeLog file, but keep the maximum line length at 72
   or smaller, so that the generated ChangeLog lines, each with its
   leading TAB, will not exceed 80 columns.
+
+* Commit log keywords
+
+  - GnuPG-bug-id :: Values are comma or space delimited bug numbers
+                    from bug.gnupg.org pertaining to this commit.
+  - Debian-bug-id :: Same as above but from the Debian bug tracker.
+  - CVE-id :: CVE id number pertaining to this commit.
+  - Regression-due-to :: Commit id of the regression fixed by this commit.
+  - Fixes-commit :: Commit id this commit fixes.
+  - Reported-by :: Value is a name or mail address of a bug reporte.
+  - Suggested-by :: Value is a name or mail address of someone how
+                    suggested this change.
+  - Co-authored-by :: Name or mail address of a co-author
+  - Some-comments-by :: Name or mail address of the author of
+                        additional comments (commit log or code).
+  - Proofread-by :: Sometimes used by translation commits.
+  - Signed-off-by :: Name or mail address of the developer
+
+* Sending patches
+
+  - submitting patches, and subsequent discussions around them,
+    happens via the [hidden email] public mailing list
+
+  - send your patches to that list, preferably PGP/MIME signed. Make
+    sure to include a mention of 'libgpg-error' in the subject line,
+    the list is used for several different projects
+
+  - if you're working from the git repo, here's a suggested workflow:
+
+    - hack hack hack
+
+    - commit your changes; group changes into easily-reviewable commit
+      units, feel free to submit several patches at once
+
+    - e.g. if you want to submit a single patch on top of master, do:
+      git send-email --to=[hidden email] --annotate -1
+      (please put a mention of libgpg-error into the subjects,
+      annotate lets you do that)
+
+    - e.g. if you have two commits on top of master, do:
+      git send-email --to=[hidden email] --annotate --cover-letter -2
+      (that prompts you for a summary mail to precede your actual
+      patch mails)
+
+    - use --dry-run to test your setup
--
2.13.6


_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Daniel Kahn Gillmor-7
On Thu 2018-02-01 14:24:07 +0100, Thorsten Behrens wrote:
> Signed-off-by: Thorsten Behrens <[hidden email]>
> ---
>  doc/HACKING | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)

This looks like a reasonable update to me.  Werner, if you agree with
the recommendations there, please merge!

    --dkg

_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Damien Goutte-Gattat
In reply to this post by Thorsten Behrens
Hi,

On 02/01/2018 01:24 PM, Thorsten Behrens wrote:
> +  - send your patches to that list, preferably PGP/MIME signed.
                                        ^^^^^^^^^^^^^^^^^^^^^^^^^^

As far as I know, git send-email does not allow to do that. (Or if it
does, I never found how to do it--when I looked for that feature, I
found nothing else than an a old bug report complaining precisely that
it was not supported [1].)

It seems strange to ask for "preferably PGP/MIME signed" patches and to
suggest a workflow which does not support it.

Damien

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=534251


_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

signature.asc (499 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Todd Zullinger
In reply to this post by Thorsten Behrens
Thorsten Behrens wrote:

> +* Sending patches
> +
> +  - submitting patches, and subsequent discussions around them,
> +    happens via the [hidden email] public mailing list
> +
> +  - send your patches to that list, preferably PGP/MIME signed. Make
> +    sure to include a mention of 'libgpg-error' in the subject line,
> +    the list is used for several different projects
> +
> +  - if you're working from the git repo, here's a suggested workflow:
> +
> +    - hack hack hack
> +
> +    - commit your changes; group changes into easily-reviewable commit
> +      units, feel free to submit several patches at once
> +
> +    - e.g. if you want to submit a single patch on top of master, do:
> +      git send-email --to=[hidden email] --annotate -1
> +      (please put a mention of libgpg-error into the subjects,
> +      annotate lets you do that)
> +
> +    - e.g. if you have two commits on top of master, do:
> +      git send-email --to=[hidden email] --annotate --cover-letter -2
> +      (that prompts you for a summary mail to precede your actual
> +      patch mails)
I think it would be better to suggest setting the
format.subjectPrefix option to make this easier.  E.g.:

    $ git config format.subjectPrefix 'PATCH/libgpg-error'

It's generally better to use 'git format-patch --cover-letter ...'
to generate and edit the cover letter and be sure it looks
good, then use 'git send-email $patch_files'.  Using git
send-email to directly drive 'git format-patch' makes it far
too easy to send out the wrong patch series.

The format.subjectPrefix option applies whether you run git
format-patch or git send-email and let it call format-patch
though.

--
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Living your life is a task so difficult, it has never been attempted
before.


_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

signature.asc (555 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Daniel Kahn Gillmor-7
In reply to this post by Damien Goutte-Gattat
On Thu 2018-02-01 16:20:25 +0000, Damien Goutte-Gattat wrote:

> Hi,
>
> On 02/01/2018 01:24 PM, Thorsten Behrens wrote:
>> +  - send your patches to that list, preferably PGP/MIME signed.
>                                         ^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> As far as I know, git send-email does not allow to do that. (Or if it
> does, I never found how to do it--when I looked for that feature, I
> found nothing else than an a old bug report complaining precisely that
> it was not supported [1].)
>
> It seems strange to ask for "preferably PGP/MIME signed" patches and to
> suggest a workflow which does not support it.

maybe if we state a preference it can be used to encourage bugfixes
elsewhere in the stack?  it's certainly possible to prefer something
that you can't currently have easily.

     --dkg

_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Todd Zullinger
In reply to this post by Todd Zullinger
I wrote:
> I think it would be better to suggest setting the
> format.subjectPrefix option to make this easier.  E.g.:
>
>     $ git config format.subjectPrefix 'PATCH/libgpg-error'

And here's that suggestion in unified diff format (along
with automation of the git send-email --to=... option).
Feel free to squash this in with or without attribution.  I
don't think this warrants a signoff or DCO from me, but I'm
happy to provide one if needed.

-->8--
diff --git i/doc/HACKING w/doc/HACKING
index d379099..9d552b7 100644
--- i/doc/HACKING
+++ w/doc/HACKING
@@ -57,18 +57,21 @@
 
   - if you're working from the git repo, here's a suggested workflow:
 
+    - configure git send-email defaults:
+
+        git config format.subjectPrefix 'PATCH/libgpg-error'
+        git config sendemail.to [hidden email]
+
     - hack hack hack
 
     - commit your changes; group changes into easily-reviewable commit
       units, feel free to submit several patches at once
 
     - e.g. if you want to submit a single patch on top of master, do:
-      git send-email --to=[hidden email] --annotate -1
-      (please put a mention of libgpg-error into the subjects,
-      annotate lets you do that)
+      git send-email --annotate -1
 
     - e.g. if you have two commits on top of master, do:
-      git send-email --to=[hidden email] --annotate --cover-letter -2
+      git send-email --annotate --cover-letter -2
       (that prompts you for a summary mail to precede your actual
       patch mails)
 
--
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You cannot propel yourself forward by patting yourself on the back.


_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

signature.asc (555 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Todd Zullinger
In reply to this post by Daniel Kahn Gillmor-7
Daniel Kahn Gillmor wrote:

> On Thu 2018-02-01 16:20:25 +0000, Damien Goutte-Gattat wrote:
>> On 02/01/2018 01:24 PM, Thorsten Behrens wrote:
>>> +  - send your patches to that list, preferably PGP/MIME signed.
>>                                         ^^^^^^^^^^^^^^^^^^^^^^^^^^
>>
>> As far as I know, git send-email does not allow to do that. (Or if it
>> does, I never found how to do it--when I looked for that feature, I
>> found nothing else than an a old bug report complaining precisely that
>> it was not supported [1].)
>>
>> It seems strange to ask for "preferably PGP/MIME signed" patches and to
>> suggest a workflow which does not support it.
>
> maybe if we state a preference it can be used to encourage bugfixes
> elsewhere in the stack?  it's certainly possible to prefer something
> that you can't currently have easily.
I have my doubts that git send-email will ever directly
support PGP/MIME.  But if signed patches are desired,
there's no reason not use git format-patch to generate a
patch (whether a single patch or a series with a cover
letter) and then use any decent mail client to send the
patch(es).

Using git send-email is generally just convenient for folks
whose mail clients would otherwise mangle the whitespace,
wrap the text, or otherwise bugger the patch content.

It's been a while since I've delved deeply into the PGP/MIME
specs, but does it ensure that no such whitespace mangling
will occur?  Obviously, once the message is generated the
signature ensures nothing is changed.  What I'm not sure of
is whether any part of the specification allows or requires
any sort of whitespace or other changes.

--
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Abandon the search for Truth; settle for a good fantasy.


_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

signature.asc (555 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Daniel Kahn Gillmor-7
On Thu 2018-02-01 15:55:48 -0500, Todd Zullinger wrote:
> I have my doubts that git send-email will ever directly
> support PGP/MIME.  But if signed patches are desired,
> there's no reason not use git format-patch to generate a
> patch (whether a single patch or a series with a cover
> letter) and then use any decent mail client to send the
> patch(es).

you're suggesting a mail client that can take an existing file that
contains an RFC822-formatted message, and will let the user sign and
send it without this kind of stuff:

> Using git send-email is generally just convenient for folks
> whose mail clients would otherwise mangle the whitespace,
> wrap the text, or otherwise bugger the patch content.

i'd like to know which mail clients you use that really make that
workflow easy :)

> It's been a while since I've delved deeply into the PGP/MIME
> specs, but does it ensure that no such whitespace mangling
> will occur?  Obviously, once the message is generated the
> signature ensures nothing is changed.  What I'm not sure of
> is whether any part of the specification allows or requires
> any sort of whitespace or other changes.

PGP/MIME will preserve the whitespace.  Inline PGP signatures are a
whole other kettle of (messed up) fish, and should not be attempted.

       --dkg

_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Todd Zullinger
Hi Daniel,

[Apologies for the relative length of this reply.  Brevity
is not my strong suite. ;)]

Daniel Kahn Gillmor wrote:

> On Thu 2018-02-01 15:55:48 -0500, Todd Zullinger wrote:
>> I have my doubts that git send-email will ever directly
>> support PGP/MIME.  But if signed patches are desired,
>> there's no reason not use git format-patch to generate a
>> patch (whether a single patch or a series with a cover
>> letter) and then use any decent mail client to send the
>> patch(es).
>
> you're suggesting a mail client that can take an existing file that
> contains an RFC822-formatted message, and will let the user sign and
> send it without this kind of stuff:
>
>> Using git send-email is generally just convenient for folks
>> whose mail clients would otherwise mangle the whitespace,
>> wrap the text, or otherwise bugger the patch content.
>
> i'd like to know which mail clients you use that really make that
> workflow easy :)
Mutt doesn't do too badly here.  Receiving a PGP/MIME signed
patch can be easily decoded and saved, then applied using
git am.  It's only a matter of using decode-copy versus copy
when saving the patch(es) (or using $pipe_decode for someone
piping a patch directly from mutt to git am).

That said, my main point is that I don't think it is likely
that git send-email will support PGP/MIME natively soon, if
ever¹.  And as such, I think describing a workflow that is
not possible in the HACKING file isn't the most friendly
thing (essentially what Damien said).

It seems better to me to either leave out the ", preferably
PGP/MIME signed" bit or describe a workflow for someone
reading the HACKING file that can reasonably be followed.
What that workflow is depends a bit on how the GnuPG
maintainers incorporate patches from the list, which I don't
know.

> PGP/MIME will preserve the whitespace.  Inline PGP signatures are a
> whole other kettle of (messed up) fish, and should not be attempted.

Teaching most mail clients to save a message without the
PGP/MIME is probably trickier than with mutt, but I imagine
maintainers and users who have a git workflow based on email
use mail clients where this is feasible.

If GnuPG wants to use signed patches, that's certainly
great.  It may be easier to do so using a slightly different
workflow, depending on how difficult it is for new
contributors to generate PGP/MIME formatted messages from
their patches.

Attaching messages and then signing them may be easier.  Of
course, some mail clients won't show the patches "attached"
inline, but some mail clients just suck more than others. :)

Another option might be to recommend that users generate
patches with git format-patch² and then process them using
another script which can PGP/MIME sign them.  That script
could either send the signed patches directly or feed them
to git send-email (as far as I know, git send-email won't
have trouble with already signed messages, but I haven't
tested this).

I don't know if there's already a convenient script to
create PGP/MIME messages or not.  It would be handy to have
in many situations, I imagine, and very well may already
exist.  If so, it should be relatively easy to suggest to
users whose mail clients don't make this as easy as mutt
(or, I presume gnus).

¹ If someone wants git send-email to support PGP/MIME
  signing, they would need to propose patches to git.  It
  would likely need to be done using either Perl or C (and
  rewriting git send-email in C first) to incur no
  significant new requirements in git.

  I say simply this based on my following of the git
  community over the years (and partly as a distro packager
  of git who would prefer that a core tool like git
  send-email avoids growing many more dependencies).

² Recommending git format-patch and then git send-email is
  better in any case, IMO.  Junio has stated a few times on
  the git list that allowing git send-email to drive git
  format-patch seems like a bad decision.  Most recently,
  https://public-inbox.org/git/xmqqo9lbt75o.fsf@.../

--
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Money can't buy happiness, but it sure makes living in misery easier.


_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

signature.asc (555 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Werner Koch
In reply to this post by Todd Zullinger
On Thu,  1 Feb 2018 21:41, [hidden email] said:

> And here's that suggestion in unified diff format (along
> with automation of the git send-email --to=... option).

Thanks.  I applied this but also changed autogen.sh to run git config
too.


Shalom-Salam,

   Werner

--
#  Please read:  Daniel Ellsberg - The Doomsday Machine  #
Die Gedanken sind frei.  Ausnahmen regelt ein Bundesgesetz.

_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

attachment0 (233 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH libgpg-error] doc: clarify patch submission workflow

Damien Goutte-Gattat
In reply to this post by Todd Zullinger
Hi GnuPG folks,

On 02/04/2018 04:55 AM, Todd Zullinger wrote:
> Another option might be to recommend that users generate
> patches with git format-patch² and then process them using
> another script which can PGP/MIME sign them.
> [...]
> I don't know if there's already a convenient script to
> create PGP/MIME messages or not.

Several years ago, I wanted to understand how MIME messages are
constructed and I wrote a small program that can take a message body and
turn it into a PGP/MIME-signed message.

I forgot about this program almost as soon as I finished it. The above
discussion reminded me of it. As it turns out, this program could be
used for the purpose described by Todd.

The program is called fmail and may be found on my homepage [1]. It
reads a message (such as one produced by git format-patch) on its
standard input and, if called with the -s option, emits a
PGP/MIME-signed message on its standard output. The signed message may
then be sent with presumably any mail submission agent (I tested with
both msmtp and git send-email).

With this program, the workflow for a single patch could be the following:

   $ git format-patch -1 --stdout [other format-patch options] | \
     fmail -s | git send-email

And for a patch set:

   $ git format-patch [format-patch options]
   $ for mail in *.patch ; do fmail -s < $mail > $mail.signed ; done
   $ git send-email *.signed

Note: I am *not* advocating the use of my program to send patches to
gnupg-devel (actually I don't even like advertising it here, I am doing
it now only because it happens to be relevant to the discussion). My
point is mainly that the "another option" proposed by Todd is doable.

[1] https://incenp.org/dvlpt/fmail.html


_______________________________________________
Gnupg-devel mailing list
[hidden email]
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

signature.asc (499 bytes) Download Attachment