Provide a mechanism for issue summaries (#1036132) · Issues · project / drupalorg

Provide a mechanism for issue summaries

>>> [!note] Migrated issue   Reported by: [dww](https://www.drupal.org/user/46549) >>> <h3>Problem/Motivation</h3> Communication is at the very center of everything we do as a community, and issue queues are the primary mechanism through which we communicate. However, the Drupal contributor community collectively loses hours of time each and every day in discussions, because there is no consistent way to find out what the current state is of any given non-trivial issue. Once an issue hits about 20+ replies or so, a number of things start happening: <ul> <li>Contributors not yet part of the discussion shy away from it because it's too intimidating. This dramatically reduces the number of people who can fix it.</li> <li>Where new contributors do wade in and get involved, they often just skip to the bottom of the discussion and start chiming in there, often repeating information that's already been hashed through 20 replies before. This is frustrating for all involved, and makes the issue even longer when this is pointed this out.</li> <li>Patch reviewers and committers both must read the entire issue top to bottom to understand what's happening. This dramatically increases the amount of time it takes to perform patch reviews and commits, leading to patch stagnation.</li> <li>Even in the rare cases that someone has taken it upon themselves to make an issue summary as one of the comments in the thread, the trick then becomes finding that issue summary in #99 of 128 comments, and trying to tell if it's still up to date given the other 10-15 replies below it.</li> </ul> This is fundamentally the single biggest Drupal community performance issue, and bites us absolutely everywhere, regardless if the problem trying to be solved is in core, contrib, or Drupal.org itself. Fixing it will make solving every single problem we solve thereafter (including improvements to how issue summaries are done) much, much easier. <h3>Proposed resolution</h3> Originally, the proposed fix was to flag one or more individual comments as an "Issue summary". However, this plan was abandoned for the following reasons: <ol> <li>In order to make a small correction/clarification to someone's issue summary, one has to re-copy someone else's comment and then paste it again. If someone else wants to make a small clarification to that, they have to re-copy and paste it again as well. This needlessly elongates the issue and makes it more sprawling and difficult to read and understand.</li> <li>There's also no way to "diff" separate comments to see what was added or changed between revisions.</li> <li>And finally, the infra team has nixed the proposal to deploy Flag module for comments due to the unacceptable performance hit on d.o (see <a href="http://drupal.org/node/1036132#comment-4352626">#60</a>).</li> </ol> Previous attempts have also involved a separate summary node, node-referenced to the issue, as well as a single "summary" field on an issue that's editable, but this too required putting new code on Drupal.org and thus got stalled. Therefore, what's being proposed instead is the simplest thing that could possibly work, namely to make initial issue bodies themselves editable (essentially "wiki" pages like handbook pages), and use the initial post as the issue summary. This has the following advantages: <ol> <li>Does not require new modules to be tested, approved, and deployed to Drupal.org, which has killed the last two attempts (at least) of fixing this issue.</li> <li>Easy to tell when a summary has been edited, what was changed, when, and by whom thanks to node revisions + diff module.</li> <li>No fanciness; works with via same standard permissions as handbooks do, which has already been tested and approved for use on d.o.</li> </ol> The following concerns are acknowledged, but being pushed to follow-up issues so we can gather data on actual usage sooner: <ol> <li>Shepherding of issues edits on top of maintaining queues for contrib.</li> <li>No comment stream integration means dashboard widget behaviour is inconsistent.</li> <li>No comment stream integration means updates do not flow into discussion.</li> <li>Original post retention is not enforced and could be relegated to revision hunting.</li> </ol> <h3>Remaining tasks</h3> This code has been deployed! YAY! :D However, doing this uncovered a bug with Project Issue module (actually with node_save()) that needs to be fixed: <a href="https://www.drupal.org/project/drupalorg/issues/1217286" title="Status: Closed (won't fix)">#1217286: Posting a comment changes too many issue node revision properties</a> Not a blocker, but unit tests are also highly desired from the Project issue module maintainer for the following issue identified during testing: <a href="https://www.drupal.org/project/project_issue/issues/1178288" title="Status: Needs work">#1178288: Data loss of uploaded files when re-editing issue</a> <h3>User interface changes</h3> <ul> <li>Additional description added to top of issue form field to explain the mechanics.</li> <li>Display of issue nodes has changed slightly: - Heading of "Issue summary" at the top - "Revision X by USERNAME on DATE" at the top to indicate it's been edited. - Link "Revision X" to the diff if there are more than one revision. </li> <li>Inline notifications that the summary has changed</li> </ul> <h3>API changes</h3> None. <h2 id="follow-up">Follow-up issues</h2> <ol> <li><a href="https://www.drupal.org/project/drupalorg/issues/1217646" title="Status: Closed (cannot reproduce)">#1217646: Tweak UI of issue summaries</a></li> </ol> <h2 id="unrelated">Unrelated issue commonly confused with this one</h2> <ol> <li>The <cite>Change records for this issue</cite> sidebar is not related to this issue. See <a href="https://www.drupal.org/project/infrastructure/issues/648218" title="Status: Closed (fixed)">#648218: Make API changes in Drupal core be nodes</a> and <a href="https://www.drupal.org/project/drupalorg/issues/1217118" title="Status: Closed (fixed)">#1217118: [meta] Followups for API change nodes</a></li> </ol> <h3>Original report by dww:</h3> Splitting this off from <a href="https://www.drupal.org/project/project_issue/issues/569552" title="Status: Closed (won't fix)">#569552: Provide a mechanism for issue meta discussions</a> from rfay: <blockquote> Bojhan, DamZ and I just talked a bit about this and DamZ has an alternate proposal: He suggests a checkbox on a comment which marks it as an issue summary, and then the summary at the top of the node would have links to issue summaries which have been posted. It also does not require adding comment_driven, which he is opposed to. I would be fine with this. It allows access to good issue summaries from the top of the issue, and allows multiple issue summaries (which might be associated with different cycles within the issue). </blockquote> The older issue had been moved into a related but separate problem of being able to highlight or flag specific comments as issue summaries. The idea is that it's hard to tell which comments in a large issue are a useful place to read what's up with the issue, instead of trying to wade through dozens (sometimes hundreds) of replies. However, issue summaries could be useful for all issues, not just the problem of meta issues to coordinate a set of related tasks (which is what #569552 is really about), so I'm splitting this off into a new issue. DamZ wrote a little module for this: <a href="https://github.com/damz/comment_highlight">https://github.com/damz/comment_highlight</a> jhodgdon asked if this couldn't be implemented using <a href="http://drupal.org/project/flag">http://drupal.org/project/flag</a> -- good question donquixote pointed out "Now everyone can tag their comment a "summary", but i assume in most cases people will be honest." Right, that's a huge concern I have about this approach. See: <a href="https://www.drupal.org/project/documentation/issues/917880" title="Status: Closed (fixed)">#917880: Write a handbook page about how issue tags are intended to be used</a> <a href="https://git.drupalcode.org/project/drupalorg/-/work_items/1023108" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/drupalorg/-/work_items/1023108</a> for example. Ever since the "Issue tags" field is quite visible on issue comments (I'd really love to know when that changed), people add worthless tags all the time because they can (and think they should). While I'm skeptical that "in most cases people will be honest", I have absolutely no faith that most people will understand whatever this new checkbox is -- I predict tons of misuse (even if not abuse as such). So, if we go down this road, we need a way to uncheck the box or unflag. And, I think this should be hidden in the default comment UI (at least hidden behind a collapsed fieldset or buried under a vertical tab, etc). Yes, I think you should have to click (at least) twice to use this feature.

issue