Add explicit field/section for steps to reproduce

I asked for an update of Issue summary standards http://drupal.org/node/1155816 of through #1508106: Proposal to add new section to issue summary template with a similar request.

The issue summary template already says in Problem/Motivation that you should include the steps to reproduce. Maybe what we should do is to have the Template be the default value for the issue body when you are filing an issue?

IMO, adding a "steps to reproduce" field on an issue, or a "steps to reproduce" section of the issue summary, is not going to really give you better information from the original issue reporters. Most non-developers reporting a bug don't know what level of detail they would need to include, and most developers would hopefully already be including how to reproduce the bug when they report it (one would hope anyway).

But in spite of being sceptical about whether it would really solve any problems to do so, I have no problem separating out "steps to reproduce" from the "problem" section in the issue summary template. Doing so is an easy matter of editing a drupal.org docs page. But most people don't use the issue summary template when reporting a bug anyway, do they?

As a practical matter, adding a separate field to the issue itself is a much harder task involving doing something to a project* module, and then you'd also have to figure out how to edit it (comments or when editing the node body), where to display it, etc. It seems like it's likely to be rather clunky.

When on http://drupal.org/node/add/project-issue/drupal the blue box states:

Learn how to report an issue. Use the issue summary template to summarize the issue in the Description field below. Others can also change the summary. Editing the summary does not subscribe you to the issue or notify subscribers, so add a comment describing your changes after any significant edit.

A UX improvement would be to merge all text into one 'box'.

@clemens.tolboom: See #1472994: Guidelines on issue node add form need a UX overhaul for that sort of thing.

Generally, I'm opposed to making the issue form more complicated than it already is. I agree with jhodgdon's assessment in #5 that this is a cultural problem, not a UI/technical one. Further, I'd be -1 on including the summary template by default but it'd be slick to have a bueditor button to insert it for you automatically.

My vote on this issue is "won't fix", but I don't want to stifle progress or initiative so I'll leave this open for further brainstorming + discussion.

Thanks,
-Derek

Merging the information into one block might be desirable... Keep in mind that each project can independently define/edit the information that is shown below, but the blue-box and the "security issues" part apply across all projects. So the formatting could happen, but it would be merging information from two different sources.

Regarding the formatting and presentation of the Drupal Core instructions (the lower part), that would be an issue to file in the Drupal project, because the Drupal project maintainers have control over those instructions.

For the record, I didn't actually say that in #5 that it was a "cultural problem".... But I don't think that it's a UX issue really, so maybe what I said was equivalent to saying it's a cultural problem.

The thing is, even if there is clear guidance and a clear UI saying you need to include steps to reproduce an issue, that is not necessarily going to result in better issues that include complete steps to reproduce them. At least, in my experience of 20+ years as a professional software developer, I have encountered very few end users of any software (even statistical software that required scripting to use at all) who could write a good issue report including the right level of detail. The end users, and even the professional software support team who might be reporting the bug on their behalf, usually just want to say "this is broken" and very rarely, even if asked directly, provide anything close to the level of detail you would need about what they were doing when they observed the bug, saw the error message, or whatever.

That's not to say that we couldn't provide better guidance and a better UX... I just have doubts about whether it would actually solve the problem, assuming that the problem is that issues are coming in with insufficient information about how to reproduce the bug.

#10 perfectly sums up what I mean by a "cultural problem". You can add my nearly 20 years of experience of developing open source software, most of that on a university research project with very technical end-users who still wouldn't provide sufficient detail in the vast majority of bug reports. I'm not saying the issue UI is great, but I don't think adding another separate field for this is going to get you the results you want. To get detailed bug reports with clear steps to reproduce, we need to train people just like we have to train people contributing patches on code style, APIs, writing self-documenting code, etc. We need a culture of useful bug reports. Maybe some UI fixes could contribute in a small way towards shifting that culture, but I can't see how it's going to be sufficient, or even the primary thing. If it happens at all, it needs to be one tactic in a much larger strategy for shifting this culture (to the extent that's even possible in the bulk of cases). Further complicating the issue form without a clear strategy for actually addressing the underlying problem here doesn't seem wise. I'd rather the form was simple and people actually reported bugs, even if it takes a few iterations to get enough useful info, than to have a form so overwhelming with fields and options that people just give up and don't bother reporting the bugs at all.

@dww : thanks for the link to #1472994: Guidelines on issue node add form need a UX overhaul

My point was a mere reaction the issue summary

Frankly almost no one seems to read this.

I myself overlook the big space as I try to find the first edit box asap. Then start looking for clues what to do. But those big hints are scrolled out of screen.

Regarding the injection we do have a Dreditor #1277974: Button to prepend the 'Issue summary standard' template into Issue body.

Problem

• People don't state what their problem is.

Goal

• Improve issue resolution times by suggesting a proper structure for communicating a problem.

Details

• People have a problem.
• People don't know how to communicate a problem. (Wasn't teached in school.)
• People don't know what information needs to be communicated so the problem can be resolved.
• Contributors who want to help resolve a problem need at least basic information about the problem in order to do so.
• drupal.org attempts to point people to guidelines for how to communicate a problem, but people neither read nor follow those.

Proposed solution

1. Paste the issue summary template into the body of new issues, so people use it.
2. Revise and optimize the issue summary template to make it work for i) all issue types, ii) all projects, and most importantly, iii) novice/non-technical people.
3. Remove or move the link to issue summary guidelines. (optional)

RE #14 - +1 if we can figure out Proposed Solution item #2. :)

http://drupal-association.ideascale.com/

Improve issue form to encourage posting steps to reproduce (40 votes)

Updated issue summary.

I wonder, if we can redesign the messages to actually achieve this - they havn't received much love.

@xjm Would this be acceptable? Its a little less direct.

@Bojhan do you read the message? I'm afraid I read them once per project.

Adding these steps to the template gives us at least the opportunity to show what steps we want. People can always delete the steps.

See also #1393226: Encourage use of issue summary template, which might set a default value for the issue summary.

Now that these are fixed/deployed:
#1393226: Encourage use of issue summary template
#2281761: Add "Steps to reproduce" section to "Bare issue summary template" for dreditor and default value for new issues
I think 'Closed (works as designed)' is the most appropriate status here. Any objections?

Thanks,
-Derek

p.s. Apologies for 8-years-ago-me being hostile to the idea of at least asking for the steps to reproduce. I'm sure many folks still won't fill this in, or will do so in unhelpful / incomplete ways, but anything is better than nothing. ;)

I came after looking at #2173425: [META] Merge DrupalMentoring.org features into Drupal.org. I agree with dww that this now works as designed. I'll go ahead and change the status.