Issue summary field

The Issue summary field on an issue is a concise overview of a full issue report. It is found in the Issue summary and metadata section of the issue form.

The issue summary is the key source of information for core developers, code reviewers and users. Thus, is should be complete, accurate and up to date. If an issue summary is not clear or up to date, maintainers may mark your issue "Needs work" for an issue summary update.

Use the Issue Summary Template examples below to help complete your issue summary.

Use the template below to create an issue summary in a standard format. Some of the sections only apply to software issues. There are templates for other types of issues in the Special issue summary templates section.

General guidelines for summaries

• Either the template on this page or one of the alternative issue summary templates, as appropriate, should be used.
• You should be able to understand the issue and its current status after reading the summary.
• The summary should use short, clear sentences.
• It should use markup for better readability (lists, code snippets, subheaders, etc.).
• It should Identify the key points rather than quoting whole paragraphs.
• It can include links to particular comments if necessary, but should not only link those comments.
• The UI and API changes sections can be left as "TBD"; file followup tasks for documenting these.

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.)

<h4 id="summary-steps-reproduce">Steps to reproduce</h4>
(Detailed instructions on how to reproduce the issue, including exact versions used, specific paths to visit, what actions to take, 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-data-model-changes">Data model changes</h3>
(Database or configuration data changes that would make stored data on an existing site incompatible with the site's updated codebase, including changes to hook_schema(), configuration schema or keys, or the expected format of stored data, etc.)

<h3 id="summary-release-notes">Release notes snippet</h3>
(Major and critical issues should have a snippet that can be pulled into the release notes when a release is created that includes the fix)

<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

When you create an issue, you will see the issue summary field in the form, and the issue summary template for the project will be inserted in it. The link at the top of the page for How to report an issue will get you to information about all of the fields on issues, including the issue summary.

For an existing issue, the current value of the issue summary field is shown (formatted into nice HTML output) at the top of the issue. The source HTML for the summary is located in the "Issue summary & relationships" section of the issue page, below the comment form. You can edit the summary, along with other issue fields, when you add a comment to an issue.

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?
• If you are reporting an issue in the Documentation project, the User Guide project, or another working group that deals with documentation, make sure to include the URL of the page you are discussing in your issue summary.

For some more general tips on writing helpful descriptions, also see the non-Drupal specific How to Report Bugs Effectively.

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 or merge request.
• Approaches that have been tried and ruled out.
• If there isn't consensus about the approach in the patch or merge request, a list of all proposed approaches and pros/cons/concerns for each.
• Links to relevant API documentation or other resources.
• Known workarounds.
• Add a link to the merge request or patch that contains the most up-to-date work to be committed.

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.
• 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.

Data model changes

Description of any database or configuration data model changes that would make stored data on an existing site incompatible with the site's updated codebase.

Example

Example needed!

Details to include

• Include the detail necessary to write a hook_update_N() that will make the needed update to stored data.
• Specify whether the change is a change to database tables, stored configuration, etc.
• Document the "before" and "after" for the change.

Release notes snippet

A summary, to be used for any significant change, of the impact this change has and who is affected. The summary should be clear and succinct. People for whom English is not their first language should be able to understand it.

Release note snippets may be used for both the release notes and the release highlights. The release notes summarize the disruptive changes in a release. Whereas, the release highlights summarize the improvements in a release.

Major and critical issues that do not include a release notes snippet may be set to "Needs work" at committer discretion. Such issues are tagged with the "Needs release note" issue tag.

Release managers decide if a release note snippet is used in the release notes.

Examples

• In order to provide secure REST support for file uploads, viewing public files now requires the "access content" permission. This may require changes to automated tests, but should not affect most sites (since "access content" will already typically be granted). Ensure that the "access content" permission is granted to the relevant roles if you have unusual, custom file handling. File download permission is not affected.

• Modules using the EntityListBuilder or ConfigEntityListerBuilder classes to generate administrative interfaces should note that these now add destination parameters to links by default. In most cases this is a UX improvement, but you may want to confirm that any entity forms not using a standard submit action redirect to the correct location.

• When Drupal-to-Drupal migrations are run through the user interface, the site owner will now be warned if the migration might overwrite existing data. However, a similar fix is not yet available for Migrate Drush, so site owners running migrations on the command line should take care to ensure data is not overwritten.

• In earlier releases, the route cache on multilingual sites could sometimes become corrupted, leading to "page not found" errors for vaild pages. This is now resolved.

Details to include

• Explain who is affected by the change. For example, site owners, developers, themers etc.
• Describe the behavior before the change and the behavior after the change.
• Link to the change record for further details. (For accessibility, the link text should be descriptive and meaningful out of context.)