Issue etiquette

Every community has behavioral norms. This page describes the etiquette used with project issues in the Drupal community.

Use these guidelines to get faster and better help from project maintainers.

Things to do in issues

1. Report the issue in the correct project or place. See the issue reporting section of the Community page for more details.

2. Check that you're on the latest version before reporting an issue.

3. Download the latest development version and see if your issue has already been fixed there.

4. Read relevant documentation before creating an issue.

5. Try to get help from the community by other means. Refer to Contact Us to find support options.

6. Search the issue queue for the same or similar issues to the one you're having.

7. If you find a similar issue, consider whether your issue is really the same or you should create a new issue. If the issue is "Closed", very few people will see your post, and some project maintainers may delete such posts as noise. Always check the status and avoid posting in closed issues. If the issue is open and you have more details that could help get the bug resolved or understood, add them. Confirming that an old bug is still relevant (if it's still open) is also helpful.

8. Use issue fields correctly, including the following:

   • Use a descriptive, human-readable title.

   • Provide as full a description of the problem as possible, using the issue summary template. More details help developers to more easily track down the problem.

   • Follow the guidelines for when to assign an issue to yourself.

   • Use the issue status field correctly, including following the review process before marking an issue "Reviewed & tested by the community".

   • Before adding issue tags, read the issue tag guidelines. Don't add random keywords to the field.

   For more information, see: Creating or updating an issue report.

9. Remember that issues tagged 'Novice' should be left for users who are new to the issue queue (not necessarily new to Drupal). When novice issues are reserved for novice contributors, we allow beginners to learn and grow, and the whole Drupal Community will benefit.

10. Come back and tell the community if a particular solution worked for you or not. If you post a question and then find an answer elsewhere, post a link to it. You will help people who come after you, which in turn will mean you are likely to get better help yourself in the future.

Things not to do in issues

1. Do not report a security problem in a regular Drupal issue. Instead, follow the security issue reporting procedure.

2. Do not be discouraged if you receive a terse or delayed response. Issues have multiple contributors who are often handling many things at once, and many contributors are writing in a language that is not their first language.

3. Do not "hijack" other issues by posting your question anywhere without considering whether it would be more logical to create a new issue.

4. Do not post links to, or otherwise advertise, a "premium" version of a Drupal project that you sell on your own website in the project's issue queue. This is spam. Posting spam here may result in your account being blocked.

5. Do not open a merge request without adding any code. Delay opening the request until you have created the code you want merged.

Constructive review comments

If a contributor on an issue has provided a solution to a problem in the form of a merge request, and you have reviewed it, you should leave a constructive comment. Start your response by thanking the contributor (be specific!) and identifying what was done correctly. Then, include specific critiques or corrections. Close your review by giving an actionable next step for the issue.

Example of a supportive, constructive review

Thanks @Druplicon! Looks like the new test follows the steps to reproduce, and the test-only change demonstrates the current failure before the fix is applied.

Two suggestions:

1. The test should not be in NodeTestBase. This is a base class that provides setup and helper methods for Node module tests. Instead, let's move the test to a class that extends NodeTestBase. See the class hierarchy on the NodeTestBase API page.
2. Note that the assertion on line 1337 would still pass even if the bug were still present. Instead of asserting that an error message is not found, add an assertion for a correct result. In this case, I'd assertResponse(200) and assert that the node's title text is found.

So, the next step is to update the merge request by moving the test into a child class and changing the last assertion. In the issue comment, make clear that the test fails without the fix and passes with the fix.

Example of what not to write

Thanks but this is totally wrong. You can't put the test in that class. Also the last assertion is bogus.

Problems with this review

• Following "thanks" with "but" makes it so that you're no longer actually thanking the person. Keep your thanks separate from criticisms.
• "Totally wrong" and "bogus" are discouraging, insulting, and needlessly emphatic (and also probably false in some degree).
• The contributor might not understand the role of base test classes in core modules. Always clarify concepts that might be unfamiliar (or link to documentation).
• "The last assertion is bogus" is unspecific and unhelpful. Say exactly what's wrong with it, and do so in a way that isn't insulting.
• Finally, it appears that not much time was put into this reply. The contributor probably spent a lot of time working on the merge request, so take the time to provide better feedback.

Resources for constructive reviews

• Criticism and Ineffective Feedback by Kate Heddleston
• Fantastic guide to giving super useful help to contributors, and managing your own ability to respond to the deluge. The Gentle Art of Patch Review by Sage Sharp via kattekrab

Attribution and credit system

When you are a maintainer of a project hosted on Drupal.org, you control the project page and the contents of the repository. It is important that you observe the etiquette regarding attribution, issue credits and the proper use of our credit system:

1. If you add attribution to yourself, also add attribution for previous maintainers that have contributed to the project.
2. When marking an issue as 'Fixed', give credit to people who actually helped resolve the issue (see Granting credit to issue contributors to learn more).
3. Do not remove the name of previous contributors to the project from README, composer.json, comments in code, or from the project page.
4. Do not abuse our credit system by duplicating small changes, such as coding standards fixes, across many issues in a single project, rather than creating a single issue for resolving them.

You may also want to read our Standards of conduct for listed services.

AI-generated contribution