Last updated October 30, 2012.
One of the maintenance tasks that always needs to be done in Drupal documentation is cleaning up the Documentation issue queue. Here are the basic steps; you may also want to watch this video on how to use the Drupal issue queues to contribute to Drupal For information on how to report issues, see the reporting Documentation issues page.
The first step is to go to the Documentation issue queue and find an open issue that looks interesting to you. Then read the issue, and take one or more of the following actions.
Note for people new to issue management: To change the component, status, title, tags, and other information about an issue, scroll down to the bottom of the issue page. There you will find a Comment form. Above the comment form, you can change the issue's title, component, status, etc. Below the comment form, you will find the "Tags" section, which you can expand in order to add and remove issue tags. After composing a comment and making all the status, title, tags, etc. changes you want, click Save.
Clean up (make the issue report clear/correct)
If...
- The issue title doesn't match the issue content
- Change the issue title to something clearer.
- The issue is filed in the wrong component
- Change the component and add a comment explaining why. There is more information on components on the reporting Documentation issues page.
- The status used was incorrect
- Fix the status to the right value, with a comment explaining why. There is more information on status for reporting issues on the reporting Documentation issues page.
- The issue summary is unclear
- Edit the issue summary. To do this, click Edit at the top of the issue. You will find a link to the issue summary template; use this template to create a better issue summary. But if you can't figure out what the reporter meant, instead change the status to "postponed (needs more info)". Add a comment explaining what you don't understand, or what additional information is needed.
- The issue is missing tags
- Add tags from the official list of Documentation issue tags
Triage (decide if it's an appropriate issue)
If...
- The issue is actually a support question
- Add this comment to the issue, and change the category to "support request" and the status to "fixed":
It looks like you need some Drupal support.
I'm sorry, but although you can create issues in the Documentation project and mark the category as "support request", we don't really handle support requests here (that option is mostly there for filing support issues for contributed modules and themes).
There are several support options listed if you click on "Community" and "Support" at the top of Drupal.org, which will take you to:
http://drupal.org/community
http://drupal.org/supportThere you can find out about the Drupal IRC channels, and the Forums, which are our two main support mechanisms in the Drupal community.
Good luck with your issue!
- The issue isn't relevant any more
- Change the issue status to "fixed", and add a comment explaining that the situation appears to have been taken care of. Avoid using status "won't fix" and "by design", as these do not address the issue's main objective. It is preferred to comment on why this issue is no longer valid and mark as "fixed".
- The issue is a duplicate of another issue
- Change the status of one of the issues to "Closed - duplicate". Add comments to both issues referencing the other issue. Keep the issue that is older, is clearer, has more information, or is already assigned.
- The issue is reporting a spam comment or spam page
- Change the issue to Project = "Drupal.org webmasters", Component = "Spam", Category = "Task" (with a clarifying comment if necessary). The web masters will delete the spam and block the user so they can't continue spamming.
- The issue is filed in the wrong project
- Change the project and add a comment explaining why. There is more information on which project issues belong in on the reporting Documentation issues page.
- The issue is not applicable or is obsolete
- Change the status to "closed (works as designed)" or another applicable status, and add a comment explaining why.
- The issue is reporting a problem with an existing regular Community Documentation page
- In general, we are trying not to use the issues queue to report problems with Community Documentation pages any more (unless they are really big issues or span several pages, a group of people wants to discuss changes or updates to a set of pages, or the page should be locked to editing). Instead, the best practice is to add a comment to the page, and change the page status to an appropriate value. So, if you find an issue that reports a not-too-big problem with a single regular Community Documentation page:
- Add a comment to the page saying "(person) reported an issue with this page: (issue link)", where (person) is the user name of the issue reporter, and (issue link) is a link to the issue. You can use the [#NNNNN] syntax to make a "pretty" link -- put the issue's node ID number in for NNNNN, and it will make a link that shows the title/status of the issue. If the issue status was "needs review", a more appropriate comment might be "(person) requested a review of this page: (issue link)".
- Edit the page to change the status to "Needs technical review" or another appropriate status.
- Edit the page to make sure the Input Format is set to "Filtered HTML", so that others can edit the page; for more information, see pages locked for editing
- If you cannot edit the page, change the issue component to "Unlock a page for editing", and add a comment explaining why.
- If you were able to complete the editing steps, change the issue status to "won't fix", with a comment like this:
We aren't using Documentation issue reports to report problems with Community Documentation pages any more. I added a link to this issue as a comment on the page. Please feel free to edit the page!
Work (help resolve/fix the issue)
Assuming you have gone through the clean-up and triage steps above, or have found an issue that is already in good shape, if...
- The issue status is "needs review"
- This indicates there is an idea or major initiative that needs review. Review the idea/initiative and add your thoughts in a comment.
- The issue indicates writing/editing to do
- If you want to write/edit this documentation:
- Assign the issue to yourself. Add a brief comment explaining what you plan to do, and when you plan to do it.
- Do the work you planned to do. Be sure to change the page status appropriately (e.g., if you think it is done, mark the page as having no problems, and if you would like the content to be reviewed, give it a "needs technical review" status).
- Return to the issue and add a comment. Un-assign the issue, and change the status to "fixed". Don't use "closed - fixed", because it makes the issue immediately invisible in standard issue queue lists.
- The issue component is "Placement/Structure/Navigation"
- If you agree with the suggestion, you can go ahead and make the placement/navigation change -- follow the steps above for "writing/editing" issues. (If you don't have permission to make the change, or if it is very major, like adding a new top-level book or totally rearranging the documentation, add the "docs admins" tag to the issue and leave a comment explaining why.)
- You don't have permission to fix the problem
- This applies to components "manage comments", "unlock pages for editing", etc. If you are not an administrator, leave these issues for someone who has permission to take care of them.
Other Considerations
- If the issue is assigned to someone, and they assigned it to themselves recently, you should probably not do much to the issue, except perhaps add a helpful comment. You could also ask if they are still working on the issue, if you would potentially like to take it over or you think it has been abandoned.