Front page | perl.perl5.porters |
Postings from March 2023
Re: perlbug UX
Thread Previous
|
Thread Next
From:
Tomasz Konojacki
Date:
March 2, 2023 00:32
Subject:
Re: perlbug UX
Message ID:
20230302013153.7020.5C4F47F8@xenu.pl
On Wed, 1 Mar 2023 20:14:11 +0000
Zefram via perl5-porters <perl5-porters@perl.org> wrote:
> Ah, I think there was a misunderstanding a few messages upthread.
> My concern has been that something the user writes as plain text might
> get erroneously treated as markup. Where you wrote about the markup
> being there to ensure correct rendering, I thought you were saying it
> was a solution to this problem that I'd raised. But you're not saying
> that, you're not addressing the user-edited part at all; you're saying
> that the markup is to ensure that the non-user-edited portion renders
> correctly if interpreted as markup. As I understand it, the problem
> that I thought there was with regard to the user-edited portion of the
> bug report absolutely does exist.
>
> I still don't have complete understanding of this, but I've reached
> a few conclusions. I'll set out what I've figured out, and then talk
> about the implications for perlbug.
>
> It seems that, firstly, you expect bug reports (from whatever source)
> to usually exist in the form of documents in GitHub's markup language.
> Not surprising, since that's where you track them nowadays. I'm guessing
> it's mandatory for them to be in that form where they're actually
> in the GitHub tracker. Secondly, where a bug report originates from
> perlbug, it is common for the text output by perlbug (consisting of the
> user-edited part combined with the auto-generated information) to be put
> directly into the GitHub tracker in such a way that it gets interpreted
> as markup-language text.
>
> perlbug specifically recommends putting its output into the GitHub
> tracker, so apparently it's an intended usage for the bug reporter to
> be the one who puts perlbug output into GitHub. For a perlbug user
> who's not on GitHub, perlbug will format and send its output as an email
> message to p5p. I'm guessing that it's common for a recipient of that
> email message to then put the bug report into GitHub.
>
> It's not clear to me whether you consider it generally correct for
> perlbug output to be put straight into GitHub as markup-language text,
> or whether you expect there to be some editing process to get it into
> the correct form. This amounts to the question of the intended form
> of perlbug's output. Is the body of it plain text, in which perlbug
> has inserted some markup to protect against mistaken treatment as
> markup-language text or to make the editing process easier? Or is
> the body always intended to be fully in the markup language? Or some
> hybrid approach? It would be quite Perlish to try to have it both ways.
>
> Regarding the markup language itself, I understand that those "```"
> marks around the perl configuration data are a way to mark the contained
> text as not containing markup. I don't know what exceptions there might
> be to that; obviously "```" itself is treated as markup, I don't know
> what else. I don't know whether that markup is for plain text generally
> or conveys some additional denotation such as that the contained text
> is the output of a computer program. I don't know how to quote "```"
> itself, or anything else that "```" blocks don't handle.
>
> The first thing to understand about the user experience that I represent
> (as a non GitHub user) is that all the above is not obvious. This is
> stuff that I've learned in the past day as a result of discussion flowing
> from my actual bug report. Even the fact that the perlbug template
> contains markup isn't obvious. I guessed that it did because I was
> familiar with the RT-era template and I have a suspicious mind.
>
> If a GitHub user is using perlbug to formulate a bug report to immediately
> be put into GitHub, and they know the process, presumably they'd write
> their user-edited part in the markup language in the first instance,
> so that the whole body of the output would constitute a markup-language
> document and could be put directly into that context on GitHub. If a
> GitHub user doesn't already know the process, they'd likely recognise the
> markup in the template, and write their bit in that format. In any case,
> they end up manually putting the output into a GitHub context where they
> know what content type is expected, and they can easily fix up at that
> stage anything they got wrong in the earlier editing.
>
> For a non GitHub user things are much less approachable. In the RT era
> the interface was editing a plain text document and then sending that
> plain text as an email message; that's all fine. But in the current
> version the user edits a document that initially contains some markup,
> and, crucially, is not told what is expected. perlbug doesn't say
> anything more about the document's format than it used to. Am I expected
> to treat this as plain text, and just put plain text in the user-edited
> section? Am I expected to produce something in this markup language?
> Which language is it? Where can I learn it? perlbug really needs to say,
> probably in the template but otherwise in the instructions that precede
> the editing session, what form of text the user should put there. If it
> is so much as desirable to use the markup language, let alone expected,
> then it needs to point at a spec for the language. At minimum it would
> need to say how to reliably cause arbitrary lines of ASCII printables
> to be rendered. Edge cases count in that endeavour.
>
> The bug report gets emitted as a mail message to be sent to p5p.
> The headers indicate that the body is plain text. If it is intended
> that the body should always be a markup-language document, then MIME
> headers should be added with an appropriate Content-Type.
>
> The user experience of not knowing the intended language of a document
> I'm called upon to write has been confusing and worrying. That's with me
> going in as a very experienced Perl user, very familiar with the former
> bug reporting process, and with the confidence to blow through the markup
> issue by asserting my own intended interpretation of the bug report.
> perlbug is quite likely to be the mode of a user's first interaction with
> the core developers -- I refer to it as an ambassadorial interface --
> so the friendliness of it is quite important. Friendly treatment of an
> emailed bug report by a human can make up for some of the concern caused
> by the submission process, but it would be better to make the mechanism
> clear up front.
>
> I do judge other software projects by the nature of the bug reporting
> and patch submission processes, and by how the developers react to
> submissions. I don't recall ever having been expected to write a bug
> report in anything other than plain text before. The perlbug process
> is deficient, but it wouldn't take much to fix it.
I don't how to put this politely, but I'm unironically fascinated how
out of touch you are. That markup language is called Markdown. It isn't
specific to GitHub, it's *extremely* common. These days users are
surprised when a website does not support it.
Anyway, my personal opinion is that perlbug serves no useful purpose. We
should change it so it just outputs the URL to our issue tracker and
nothing else.
Thread Previous
|
Thread Next