To learn, read. To know, write. To master, teach.
The issue summary initiative has four goals:
- To reduce confusion and save contributors time with clear, accurate issue summaries for core issues.
- To make reviewing core issues easier.
- To reduce the number of core issues that get buried or stalled.
- To help familiarize new contributors with core and the core development process.
(For extensive background information, see http://drupal.org/node/1036132.)
Issue summaries might be contributed in several ways:
- Individually. (I'm writing one a day; how about you?)
- Core office hours
- Issue summary sprints
How to contribute issue summaries
- Above all, read and understand the Issue Summary Standards.
- Use the working spreadsheet to coordinate with others who are working on summaries.
- Go in order and summarize the first issue you understand. Issues in the spreadsheet have been specifically prioritized. Otherwise: RTBC > NR > NW; Critical > Major > Normal > Minor; oldest issues first. See details and links to queues below.
- Read the whole issue.
- If you have any questions about the issue, ask in #drupal-contribute. If you're still not sure about something, say so in the summary!
- Read the patch to look for UI or API changes. If you're not sure whether something counts as a change, or if you can't follow the patch, ask someone to check.
- If an issue already has a summary in a comment, you can use that. Update it as needed. Reference relevant comments, e.g.
- Link the comment containing the current patch under the "Proposed resolution" header. If there are different patches for different branches of core, link each.
- Update title to reflect the current scope of the issue (if needed).
- When you are done, remove the "issue summary initiative" tag and indicate in the comment that you have added or updated the summary.
"Reviewed and Tested by Community" (RTBC) Issues
The only limitation on the resolution of RTBC issues is the committers' availability to evaluate the issue. A clear, accurate issue summary will save the committer time by framing the issue and the proposed patch, and will make it easier for the committer to quickly determine when work still needs to be done. This will result in a faster turnaround for RTBC issues, which will in turn unblock other issues. Therefore, RTBC issues are the top priority for writing summaries.
Priorities for contributing RTBC summaries
- Major and critical bugs and tasks.
- Normal and minor bugs and tasks.
- Feature requests (when core is not in code slush; otherwise, move on to NR issues).
"Needs Review" (NR) issues
Many NR issues are potentially RTBC and lack only for people to review the patch code and test the patch. An issue summary can make it easier for reviewers to understand patches, and contributors are more likely to review a patch if they don't have to spend time reading all the comments on an issue. NR issues are the next priority for summaries after RTBC issues.
Priorities for contributing NR summaries
- Major and critical bugs and tasks
- Minor and normal bugs and tasks (not tagged)
Re-testing and re-rolling patches
- Verify that the NR issue does include a patch.
- If the latest patch has not passed testbot in the past 4 weeks or so, requeue it for testing.
- Make a note in the spreadsheet if you requeue. We don't want the issue to get buried if the patch just needs a reroll.
- If you reroll a patch, read the old and new patches carefully. Make sure your patch includes all blocks of changes from the original.
What about contrib?
Core is the focus here simply because there are so many outstanding issues. Furthermore, each contrib maintainer has his or her own preferred workflow for managing issue queues, so check with the module's maintainer before altering issue summaries in that module's queue. For example, if you want to help out with the Views issue queue, check out the Views Bug Squad instead.
Really, every issue doesn't need a summary. Why did you tag this one when it's simple/only X comments/RTBC/authored by Dries?
The tag does not indicate an issue needs a summary. It's to help contributors find issues that might benefit from a summary. Or they might not. If a summary doesn't seem necessary, a contributor will go onto the next issue. Feel free to remove the tag.
It says "Revision x by Foo," but the summary was actually updated by Bar!
This is a known bug. See http://drupal.org/node/1217286.
Won't these issue summaries add yet another barrier to contribution?
The issue summaries are not required. Core committers may occasionally require an issue summary for a particularly complicated or far-reaching issue, but this will be rare. Furthermore, the summaries add a new way to contribute for individuals who might not understand core well enough to review or author patches themselves! Part of the purpose of this initiative is to lower the barrier to contribution.
If someone writes up a summary that's wrong, it will only make things worse!
Issue summaries are co-authored, which means contributors can correct mistakes. If you plan an issue summary sprint, I recommend having at least one experienced contributor check the summaries, especially to review patches for UI and API changes.
Pasting in an HTML template is really awkward, the link to the instructions isn't very visible, and someone can accidentally (or deliberately) delete a user's original post. Isn't there a better way?
The current interface for issue summaries is just a first step. It will be improved in the future.
At present, the original post becomes a wiki page, with a full revision history. If someone accidentally or deliberately removes relevant information, the previous revision can be restored. Drupal.org webmasters can also restrict edit access to the issue summary if necessary. In practice, this will be rare.
There are a number of proposals to improve the issue summary UI in the Drupal.org Customizations issue queue. Post your suggestions for improving the UI there.
Wouldn't it be better to spend your time writing issue summaries rather than tagging issues?
Well, I do both. :) The tags are used to help contributors collaborate and find issues that do not already have summaries.