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 Resources > Support 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. Don't: Report a security problem in a regular Drupal issue. Instead, follow the security issue reporting procedure.

2. Don't: 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. Don't: "Hijack" other issues by posting your question anywhere without considering whether it would be more logical to create a new issue.

4. Don't: 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. Don't: 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 patch or pull request), and you have reviewed it, you need to 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 this test follows the steps to reproduce and the failure is exposed in the test-only patch.

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 is still passing in the test-only patch. 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 create an updated patch that moves the test into a child class and changes the last assertion. Post a test-only patch followed by a combined patch, just like in #42 above.

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 patch, 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. Do not remove the name of previous contributors to the project from README, composer.json, comments in code, or from the project page.
2. If you add attribution to yourself, do also add attribution for previous maintainers that have contributed to the project.
3. When marking an issue as Fixed, do give credit to people who actually helped resolve the issue (see Granting credit to issue contributors to learn more).
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 Service listing standard of conduct, and the instructions on how to grant credit and attribution to contributors on issues.

AI-Generated Content

There is no doubt that artificial intelligence tools such as ChatGPT can be powerful ways to jumpstart code or content. However, AI systems still have significant flaws. Often times the code they produce is non-functional, and the content they create includes assertions or citations that are untrue.

When using AI in the course of making a contribution to Drupal, we require you to:

• Disclose that AI was used in crafting the code or content.
• Carefully review and test the output, to ensure it is relevant, and that it works.
• Provide human intervention to correct inaccuracies, mistakes, or broken code. 

Bulk use of AI when it is not relevant to an issue, provides broken or unusable code, or provides false information will likely result in a ban.