HELP! Drupal 8 issues need summaries

+ Needs issue summary update

The main body of a Drupal.org issue is its editable issue summary. Clear issue summaries are recommended for most Drupal core issues, and core maintainers can require them before an issue is considered for a commit.

We need more up-to-date summaries for Drupal 8 issues. Read on for how you can help, or start right away by updating the summary of an issue tagged with Needs issue summary update.

What are issue summaries?

The summary is a concise overview of an issue's purpose and current status. Summaries can be updated collaboratively as an issue progresses. There is also a standard template for issue summaries to make them easier to read. (To update an issue summary, click on the "Edit" tab for the issue.)

Why do we need issue summaries?

• Providing a clear explanation of how to reproduce a bug or what needs to be done next to resolve an issue is the most effective way to get someone to work on it.

• Up-to-date summaries save time spent reading all of an issue's comments, especially for issues with many comments. One concise, complete summary can save literally hours of the community's time.

• Summaries save time for reviewers, and Drupal has far more patch contributors than reviewers. About 20% of Drupal 8 issues are marked "Needs review," and over 900 of these have not received a new comment in over a month. The oldest have not had updates in more than a year and a half.

• Drupal 8 core maintainers in particular need to know how an issue fits into the "big picture" of Drupal 8, especially now that we are in feature freeze. Clear, current summaries will help maintainers make decisions about which patches to accept and when.

What issues need summaries?

Any Drupal core issue benefits from a clear, concise, up-to-date summary, but they are especially important for:

• Major and critical issues.
• Issues with many comments or large patches.
• Issues that introduce important architectural changes.
• Issues that have changed direction since the initial post.

When should I update an issue's summary?

• When an issue is ready for community input.
• When the summary doesn't reflect the current status.
• When the summary is unclear or doesn't answer your questions about the issue.
• When someone posts feedback on the issue that needs to be addressed.
• When an issue is tagged with Needs issue summary update, especially when a reviewer or maintainer has recently requested the update.

What should be in an issue summary?

• The target audience is a Drupal 8 developer or maintainer who is not familiar with the particular issue or the details of the particular API.
• A concise, scannable summary is far more valuable than an essay.
• Above all, a summary should identify what change is needed and why.
• For details, see the issue summary instructions.

How can I help?

How do I start?

• Review the issue summary instructions.

• When you look at a core issue, skim the summary and see if it could use an update. (Tip: Dreditor provides an inline issue summary editor that you can use while reading the issue.)

• If you find an issue unclear, add the Needs issue summary update tag.

• If an issue summary has good information but does not use the standard template, edit it and simply insert the template headers where appropriate.

• When you review a patch, double-check that the solution described in the "Proposed resolution" section accurately reflects the patch that you reviewed.

• When you do a code review on a patch, make note of any API changes you notice. (These can be added to the "API changes" section of the summary.)

How can I help more?

• Look for an issue tagged with Needs issue summary update, and help update the summary.

• Review and update the summary for a major or critical issue.

• Come to Core contribution mentoring and tell your mentor that you'd like to contribute to an issue summary.

• Try to contribute one issue summary update every day, and tweet about it with the #PatchADay tag.