Last updated September 27, 2014.

On this page:

To get help completing this task, see the Getting help completing your task page.

Goal

Take an existing Drupal Core issue, and edit it so that it has a standardized, clear, up-to-date issue summary.

Skills needed

Read/write in English competently (but your language skills don't have to be perfect). Ability to summarize.

Detailed steps

  1. Log in to Drupal.org, or create an account and then log in.

  2. Find a Drupal Core issue to work on. Issues that need summaries are tagged with Needs issue summary update. Choose an issue that has a smaller number of replies to start with (you can tackle an issue with more replies next time). Also, look for an issue title that you understand -- for instance, if you are not a programmer, and the title has a lot of programming jargon in it, you might choose a different issue.

  3. Visit the issue page by clicking on the Drupal.org issue number. If it already has an issue summary that follows the issue summary template and appears to be complete and up-to-date, pick a different issue.

  4. Read the whole issue including the comments. You will need to figure out what problem has been reported, what the proposed solution is (if any), and the effects of the proposed solution on programmers and Drupal users (if any). If you don't understand the issue at all, pick a different issue. If you need some help understanding the issue, ask in IRC channel #drupal-contribute (see Getting help completing your task).

  5. Edit the issue summary by clicking the "Edit" link at the top of the issue page (you will probably want to open the edit page in a new window/tab, because you cannot see the issue comments while you are editing). (Tip: If you use Dreditor, you can use the inline summary editor to update the summary while reading the issue.)

    • Copy the issue summary template, and paste it into the top of your editing field.
    • Update the first line of the summary to indicate the most recent comment number as of your summary update.
    • Then, follow the models on the issue summary template page to fill in the rest of the information. You will need to refer to the original issue report, as well as the comments, to figure out what the summary should say.
    • Any portions that have not yet been decided on, you can fill in as "To be determined".
    • Any areas that you are not sure about, fill in what you can and note what you are not sure about.
    • If there are long discussions on particular comments that are relevant for the summary, link to those comments.
  6. Save the issue, adding an appropriate comment to the revision log. Include your username in the log message. (The revision log displays the author of the most recent comment rather than the actual author of the summary revision.)

  7. You should now be back on the issue view page. Add a comment saying that you have just written an issue summary. Before saving your comment, also check to see whether the issue title is appropriate, and change it if not (above the comment form). Also, in the Tags section below the comment form, remove the "Needs issue summary update" tag from the list. Now save your comment.

Background and reference information

Next steps: moving beyond this task

Notes for reviewers

In general, follow the instructions for contributing as a reviewer and how to review patches. Keep in mind how to give constructive feedback.

Specific to this task:

  • Issue summaries should use the standard template.
  • 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.