[prev in list] [next in list] [prev in thread] [next in thread] 

List:       perl5-porters
Subject:    perlbug Markdown patch
From:       Zefram via perl5-porters <perl5-porters () perl ! org>
Date:       2023-04-12 19:57:39
Message-ID: ZDcNMx8h/Dv/QGJX () fysh ! org
[Download RAW message or body]

Attached is a patch tweaking perlbug to reflect the process that we've
been developing for smooth bug reporting outside GitHub.  Provided that
those who actually field emailed bug reports are satisfied with the
details implemented here, it would be a good idea to apply this patch,
and it would specifically be good to get it in before 5.38.

-zefram

["0001-in-perlbug-advise-user-about-desired-format.patch" (text/x-diff)]

From 77309603efc6d1e63edf1c33e31eb04a0f3f36e4 Mon Sep 17 00:00:00 2001
From: Zefram <zefram@fysh.org>
Date: Wed, 12 Apr 2023 20:35:44 +0100
Subject: [PATCH] in perlbug, advise user about desired format

We have established that, where a user is formulating a bug report
using perlbug, it is desired for the main body of the bug report to be
written in GitHub Flavored Markdown, for ease of importing it into the
GitHub bug tracker.  Further, where the perlbug output is mailed, it
is desired for the headers to mislabel the body as plain text, because
at least one MUA makes it difficult to handle a body that is correctly
labelled as Markdown.

This commit incorporates this knowledge into the perlbug utility, so
as to guide an unfamiliar user.  A comment is added to the portion of
the bug report template that is intended to be user edited, stating that
the content should be in GFM, and pointing at the GFM spec.  An explicit
Content-Type header is added, specifying plain text, and (for the benefit
of anyone engaging with the output as an email message) an accompanying
header is added with a comment about the mislabelling.  It would be
standards-conformant to put this comment in the Content-Type header, but
Gmail barfs on that in a way that makes the message difficult to handle.

The perlthanks process is relatively unchanged.  The perlthanks template
isn't designed to be Markdown in the way the perlbug template is, so
neither comment about Markdown gets added there.
---
 utils/perlbug.PL | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/utils/perlbug.PL b/utils/perlbug.PL
index 444816099d..979b691aff 100644
--- a/utils/perlbug.PL
+++ b/utils/perlbug.PL
@@ -86,7 +86,7 @@ BEGIN {
     $::HaveWrap = ($@ eq "");
 };
 
-our $VERSION = "1.43";
+our $VERSION = "1.44";
 
 #TODO:
 #       make sure failure (transmission-wise) of Mail::Send is accounted for.
@@ -652,6 +652,9 @@ EOF
 -----------------------------------------------------------------
 <!--[Please describe your issue here]-->
 
+<!-- Please write all of this content in GitHub Flavored Markdown,
+as described at <https://github.github.com/gfm/>. -->
+
 **Description**
 <!-- A clear and concise description of what the bug is. -->
 
@@ -1061,25 +1064,42 @@ sub _build_header {
     return $head;
 }
 
+sub _main_part_type_headers {
+    return +{
+        "Content-Type" => "text/plain",
+        ($thanks ? () : (
+            "X-Content-Type-Comment" =>
+                "(the content is actually GitHub Flavored Markdown, ".
+                "but the Perl maintainers prefer to receive it ".
+                "labelled as plain text) ".
+                "(also, Gmail can't handle that comment appearing in the ".
+                "Content-Type header)",
+        )),
+    };
+}
+
 sub _message_headers {
     my %headers = ( To => $address || 'perl5-porters@perl.org', Subject => $subject );
     $headers{'Cc'}         = $cc        if ($cc);
     $headers{'Message-Id'} = $messageid if ($messageid);
     $headers{'Reply-To'}   = $from      if ($from);
     $headers{'From'}       = $from      if ($from);
+    $headers{'MIME-Version'} = '1.0';
     if ($have_attachment) {
-        $headers{'MIME-Version'} = '1.0';
         $headers{'Content-Type'} = qq{multipart/mixed; boundary=\"$mime_boundary\"};
+    } else {
+        my $type_headers = _main_part_type_headers();
+        $headers{$_} = $type_headers->{$_} foreach keys %$type_headers;
     }
     return \%headers;
 }
 
 sub _add_body_start {
+    my $main_type_headers = _build_header(%{_main_part_type_headers()});
     my $body_start = <<"BODY_START";
 This is a multi-part message in MIME format.
 --$mime_boundary
-Content-Type: text/plain; format=fixed
-Content-Transfer-Encoding: 8bit
+${main_type_headers}Content-Transfer-Encoding: 8bit
 
 BODY_START
     return $body_start;
-- 
2.30.2



[prev in list] [next in list] [prev in thread] [next in thread]