Writing Issues

An issue is a compact request and decision record for someone else, often someone who joins the project months from now. It has to survive without you in the room. State the problem, define the desired outcome, and include enough verified context to triage it and begin the right discussion. Make unresolved questions explicit instead of guessing.

Own the submission

You are responsible for every issue you submit. Treat AI-generated text as a draft, not as evidence or a substitute for understanding. Verify every factual claim, rewrite the issue in your own words, and make sure you can explain each proposed decision. Never excuse an error or unsupported choice by saying that AI wrote it.

When assisting someone who will submit under their name, present a draft for their review unless they explicitly asked you to file it. Surface unresolved facts and decisions; do not hide them behind polished language.

Before you file

1. Read the contribution rules. Check CONTRIBUTING, the repository's AI-use policy, and its security-reporting process before drafting.
2. Search first. Open and closed issues, both. Drupal's issue etiquette puts this first for a reason: adding to an existing issue beats splitting the discussion across two. Link related issues either way.
3. Confirm it's current. Reproduce on the latest release or the current development branch before reporting. Fixed-in-dev is a common outcome.
4. Use the repo's template. If .github/ISSUE_TEMPLATE/ exists, pick the right one and complete every applicable required field. Use TBD or explain what is unknown when the project allows it; never invent an answer to complete the form.
5. One issue per issue. Two unrelated problems in one ticket means one of them gets forgotten when the other is fixed.

Titles