Last updated May 25, 2014. Created on May 12, 2011.
Edited by xjm, lizzjoy, tim.plunkett, Senpai. Log in to edit this page.

An issue summary is a concise overview of a full issue report. Issue summaries need to be written if the issue has more than a few comments and/or an average developer cannot understand the subject matter after a few minutes of study. These summaries are key sources of information for core developers, patch reviewers and users who need to skim large amounts of issues and information quickly.

To create an issue summary, click the "Edit" tab on the issue and paste in the template below.

Issue Summary Template

Also see the examples below.

<h3 id="summary-problem-motivation">Problem/Motivation</h3>
(Why the issue was filed, steps to reproduce the problem, etc.)

<h3 id="summary-proposed-resolution">Proposed resolution</h3>
(Description of the proposed solution, the rationale behind it, and workarounds for people who cannot use the patch.)

<h3 id="summary-remaining-tasks">Remaining tasks</h3>
(reviews needed, tests to be written or run, documentation to be written, etc.)

<h3 id="summary-ui-changes">User interface changes</h3>
(New or changed features/functionality in the user interface, modules added or removed, changes to URL paths, changes to user interface text.)

<h3 id="summary-api-changes">API changes</h3>
(API changes/additions that would affect module, install profile, and theme developers, including examples of before/after code if appropriate.)

<h3 id="summary-original-report">Original report by [username]</h3>
(Text of the original report, for legacy issues whose initial post was not the issue summary. Use rarely.)

How to find the issue summary and this document

The issue summary is in the issue's "Description" field. You can edit it by clicking the Edit tab on the issue.

Click the Edit link on the issue.

Then, paste in and fill out the template above. (A link to this document is displayed in the blue information box whenever you edit an issue.)

Use the issue summary template link to navigate to this page.

Add your username to the "Log message," and submit your change. Finally, add a comment to the issue indicating that you updated the summary.

Issue Summary Template examples

Problem/Motivation

A brief statement describing why the issue was filed, steps to reproduce the problem, and so on.

Example:

The security team has seen an explosion in reports of XSS vulnerabilities in contributed modules, because developers don't realize that you need to wrap check_plain() around arguments before passing them to drupal_set_title(), unlike other areas of the API, such as the l() function.

Details to include:

  • Why are we doing this? Above all, a summary should explain why a change is needed, in a few short sentences.
  • For majors and criticals: Why is the issue major or critical? For criticals, how does it block release?
  • For bugs: Steps to reproduce the issue on a fresh installation of HEAD.
  • For blockers: What issues is this blocking, and why?

Proposed resolution

A brief description of the proposed fix, and the rationale behind it.

Example:

Change drupal_set_title() so that it automatically check_plain()s page titles by default. An additional, optional $output parameter is added to the function, which can optionally be set to PASS_THROUGH, if the old unsanitized behavior is desired.

Details to include:

  • A short summary of the approach proposed or used in the patch.
  • Approaches that have been tried and ruled out.
  • If there isn't consensus about the approach in the patch, a list of all proposed approaches and pros/cons/concerns for each.
  • Links to relevant API documentation or other resources.
  • Known workarounds.

Remaining tasks

This section should cover anything that would prove useful to someone coming in and hoping to help with the issue. Is there a demo site? Do automated tests need to be written? Is cross-browser testing required? Does documentation need to be written? Etc.

Example:

  1. The patch is ready for review.
  2. A demo site has been set up at http://metrics-drupal.redesign.devdrupal.org/ where the current incarnation of this functionality has been deployed, for your testing pleasure.

    Apache user/pass: drupal/drupal
    D.o user/pass: jhodgdon/awesome

  3. Unit tests are needed for the following issue identified during testing:
    #1178288: Data loss of uploaded files when re-editing issue

Details to include:

  • Use a numbered list.
  • It helps reviewers to keep a list of all the tasks for an issue, and mark each off with a <del> tag once it has been completed.
  • For issues marked "Needs work": What needs to be fixed?
  • For postponed issues: What is the issue postponed on, and why?
  • If a reviewer has provided feedback that needs to be addressed, add a list item identifying that feedback, with a link to the relevant comment.

User interface changes

A list of changes/additions to to the user interface (broadly defined, see below), that would need to be documented in the online documentation on drupal.org, or added to help screens. This includes:

  • New or changed features/functionality that affect what any user, including administrators, experiences when using Drupal in a browser
  • New modules added or old modules removed
  • Changes or additions to URL paths
  • New or changed user interface text (anything in t())

Example:

Taxonomy administration pages have new paths: the basic page for the administrative overview of a vocabulary has changed from 'admin/structure/%taxonomy_vocabulary_machine_name', to 'admin/structure/taxonomy-vocabulary/%taxonomy_vocabulary_machine_name'.

Details to include:

  • Embed before-and-after screenshots illustrating the changes, cropped to show the relevant area. Tip: Dreditor adds a button that will allow you to embed images quickly.
  • List string changes.

API changes

Description of any API changes/additions that would affect module, install profile, and theme developers.

Example:

drupal_set_title() now uses check_plain() on the title text by default. To pass through text that has already been sanitized (e.g. using check_plain(), or the % or @ placeholders in t()), supply the constant PASS_THROUGH as the second argument. If you are currently calling check_plain(), that can be removed to avoid double-escaping. Examples:

Drupal 6.x:

drupal_set_title(check_plain($node->title));
drupal_set_title(t("@name's blog", array('@name' => $account->name)));

Drupal 7.x:

drupal_set_title($node->title);
drupal_set_title(t("@name's blog", array('@name' => $account->name)), PASS_THROUGH);

Details to include:

  • Include the detail necessary for creating a change notification.
  • Describe what changes module/theme developers would need to make.
  • Provide code examples if appropriate so that reviewers can evaluate the impact on the developer experience.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.