drupalorg-issue-helper

name	drupalorg-issue-helper
description	Quick help with drupal.org issue templates, formatting, contributing patches, and best practices. Invoke when user asks "how do I write a bug report?", "drupal.org issue template", "issue formatting", "I have a patch", "contribute back", "submit my fix", "I fixed a bug in a module", or needs help structuring issue descriptions or contributing code to drupal.org projects.

Drupal.org Issue Helper

Quick assistance with drupal.org issue templates, formatting, contributing patches/fixes, and best practices for effective bug reports and feature requests.

When to Use This Skill

Activate this skill when the user:

• Asks "how do I write a bug report?"
• Mentions "drupal.org issue template"
• Needs help formatting an issue description
• Asks about issue categories or priorities
• Wants to understand drupal.org issue best practices
• Says "I have a patch" or "I created a fix"
• Wants to "contribute back" or "contribute upstream"
• Asks "how do I submit my fix to drupal.org?"
• Mentions "I fixed a bug in a contrib module"
• Wants to contribute code changes to a drupal.org project

Quick Note on Creating Issues

drupal.org has no write API - issue creation requires the web UI.

Use /drupal-issue create {project} for a guided workflow that:

1. Generates properly formatted HTML content
2. Copies title to clipboard
3. Opens browser to the issue form
4. Guides you through submission

Or manually create issues at: https://www.drupal.org/node/add/project-issue/{project}

Contributing a Patch or Fix Back to Drupal.org

If you've already created a fix locally and want to contribute it back, here's the workflow:

Step 1: Create an Issue First

Before submitting code, you need an issue on drupal.org:

1. Search existing issues to avoid duplicates
2. Use /drupal-issue create {project} to create a new issue
3. Note the issue number (e.g., 3569261)

Step 2: Create a Merge Request

Use /drupal-mr {project} {issue_number} which will:

1. Clone the project to ~/.cache/drupal-contrib/{project}/
2. Guide you to create an issue fork on drupal.org
3. Set up the branch {issue_number}-{description}
4. Push your changes and provide the MR URL

Step 3: Apply Your Local Changes

If your fix is in a different location (e.g., your project's vendor/ or web/modules/contrib/):

# Option A: Copy changed files
cp /path/to/your/fix/SomeClass.php ~/.cache/drupal-contrib/{project}/src/

# Option B: Create a patch from your changes and apply it
cd /path/to/your/project
git diff web/modules/contrib/{module} > ~/fix.patch
cd ~/.cache/drupal-contrib/{project}
git apply ~/fix.patch

# Option C: Cherry-pick if you committed locally
git format-patch -1 HEAD --stdout > ~/fix.patch
cd ~/.cache/drupal-contrib/{project}
git am ~/fix.patch

Step 4: Commit and Push

cd ~/.cache/drupal-contrib/{project}
git add .
git commit -m "Issue #{issue_number}: Description of fix"
git push {project}-{issue_number} {branch_name}

Quick Contribution Workflow

For a complete guided workflow that handles issue + MR together:

/drupal-contribute {project}

Example: Contributing a Bug Fix

User: "I fixed a bug in the paragraphs module where nested items weren't saving correctly. How do I contribute this back?"

Workflow:
1. /drupal-issue create paragraphs
   → Creates issue, returns #3569999
2. /drupal-mr paragraphs 3569999
   → Sets up branch, you copy your fix, push
3. Complete MR in browser
4. Update issue status to "Needs review"

Official drupal.org HTML Issue Template

drupal.org expects issue descriptions in HTML format with specific headings. Use this exact structure:

<h3 id="summary-problem-motivation">Problem/Motivation</h3>
{problem_description}

<h4 id="summary-steps-reproduce">Steps to reproduce</h4>
{steps_if_bug}

<h3 id="summary-proposed-resolution">Proposed resolution</h3>
{proposed_solution}

<h3 id="summary-remaining-tasks">Remaining tasks</h3>
{remaining_tasks_checklist}

<h3 id="summary-ui-changes">User interface changes</h3>
{ui_changes_or_none}

<h3 id="summary-api-changes">API changes</h3>
{api_changes_or_none}

<h3 id="summary-data-model-changes">Data model changes</h3>
{data_model_changes_or_none}

Issue Categories

Category	When to Use
Bug report	Something doesn't work as expected
Feature request	New functionality needed
Task	Work item that's not a bug or feature
Support request	Need help using the module
Plan	Strategic planning for the project

Priority Levels

Priority	Definition
Critical	Data loss, security issue, or complete breakage with no workaround
Major	Significant impact but workaround exists
Normal	Standard priority for most issues
Minor	Nice to have, cosmetic issues, minor improvements

Bug Report Template

Use this complete template for bug reports:

<h3 id="summary-problem-motivation">Problem/Motivation</h3>
{Clearly describe what's wrong. What did you expect to happen vs. what actually happened?}

<h4 id="summary-steps-reproduce">Steps to reproduce</h4>
1. {First step - be specific}
2. {Second step}
3. {Third step}
4. {Observe the bug}

<h3 id="summary-proposed-resolution">Proposed resolution</h3>
{How should this be fixed?}

<h3 id="summary-remaining-tasks">Remaining tasks</h3>
- [ ] Confirm the bug can be reproduced
- [ ] Write the fix
- [ ] Add test coverage
- [ ] Review and merge

<h3 id="summary-ui-changes">User interface changes</h3>
None

<h3 id="summary-api-changes">API changes</h3>
None

<h3 id="summary-data-model-changes">Data model changes</h3>
None

Bug Report Best Practices

1. Be specific - "The form doesn't work" is unhelpful; "Clicking Save on the settings form shows a WSOD" is useful
2. Include versions - Always mention Drupal core, module, and PHP versions
3. Provide steps - Make it reproducible
4. Show error messages - Copy exact error text, don't paraphrase
5. Attach screenshots - Visual bugs need visual evidence
6. Check if it's a duplicate - Search existing issues first

Feature Request Template

<h3 id="summary-problem-motivation">Problem/Motivation</h3>
{Why is this feature needed? What problem does it solve?}

<h3 id="summary-proposed-resolution">Proposed resolution</h3>
{How should this feature work? Be as specific as possible.}

<h3 id="summary-remaining-tasks">Remaining tasks</h3>
- [ ] Design the approach
- [ ] Implement the feature
- [ ] Add test coverage
- [ ] Update documentation

<h3 id="summary-ui-changes">User interface changes</h3>
{Will there be new admin pages, form fields, or UI elements?}

<h3 id="summary-api-changes">API changes</h3>
{Any new hooks, services, or public methods?}

<h3 id="summary-data-model-changes">Data model changes</h3>
{New database tables, fields, or configuration schema?}

Feature Request Best Practices

1. Explain the "why" - Help maintainers understand the use case
2. Be specific - Vague requests are hard to implement
3. Consider existing patterns - Follow Drupal conventions
4. Offer to help - Maintainers appreciate contributors
5. Accept alternatives - Your solution might not be the best one

Task Template

<h3 id="summary-problem-motivation">Problem/Motivation</h3>
{What needs to be done and why?}

<h3 id="summary-proposed-resolution">Proposed resolution</h3>
{Approach to completing the task}

<h3 id="summary-remaining-tasks">Remaining tasks</h3>
- [ ] {Specific, testable task 1}
- [ ] {Specific, testable task 2}
- [ ] {Specific, testable task 3}
- [ ] Tests pass
- [ ] Documentation updated

<h3 id="summary-ui-changes">User interface changes</h3>
{If applicable, or "None"}

<h3 id="summary-api-changes">API changes</h3>
{If applicable, or "None"}

<h3 id="summary-data-model-changes">Data model changes</h3>
{If applicable, or "None"}

Support Request Template

<h3 id="summary-problem-motivation">Problem/Motivation</h3>
{What are you trying to do? What's not working as expected?}

**Environment**:
- Drupal version: {version}
- Module version: {version}
- PHP version: {version}

**What I've tried**:
1. {Approach 1}
2. {Approach 2}

<h3 id="summary-proposed-resolution">Proposed resolution</h3>
{What specific help or guidance do you need?}

<h3 id="summary-remaining-tasks">Remaining tasks</h3>
- [ ] Get answer/guidance
- [ ] Implement solution

<h3 id="summary-ui-changes">User interface changes</h3>
N/A

<h3 id="summary-api-changes">API changes</h3>
N/A

<h3 id="summary-data-model-changes">Data model changes</h3>
N/A

Title Best Practices

Good Titles

• "Form validation fails when field is empty"
• "Add support for CKEditor 5 plugins"
• "PHP 8.2 deprecation warning in EntityViewBuilder"
• "Missing translation for 'Save' button"

Bad Titles

• "It doesn't work" (too vague)
• "URGENT!!! HELP!!!" (not descriptive)
• "Bug" (meaningless)
• "Question" (doesn't describe the question)

Title Formula

{Action/Problem} + {Context/Location} + {Condition (optional)}

Examples:
- "Form validation fails when required field is empty"
- "Add bulk export option to admin views"
- "WSOD on node save with paragraphs enabled"

Issue Status Flow

Active → Needs work → Needs review → RTBC → Fixed → Closed
    ↑         ↓
    └─────────┘

Status	Who Sets	Meaning
Active	Reporter	Issue is open, being worked on
Needs work	Reviewer	Changes requested
Needs review	Contributor	Ready for review
RTBC	Community	Reviewed, ready to commit
Fixed	Maintainer	Committed to codebase
Closed	Anyone	Various close reasons

Quick Examples

Example 1: Concise Bug Report

User: "I found a bug where the paragraphs module crashes on save"

Title: WSOD when saving node with nested paragraphs

<h3 id="summary-problem-motivation">Problem/Motivation</h3>
Saving a node with more than 3 levels of nested paragraphs causes a white screen of death.

<h4 id="summary-steps-reproduce">Steps to reproduce</h4>
1. Create a paragraph type with a nested paragraphs field
2. Create content with 4+ levels of nesting
3. Click Save

<h3 id="summary-proposed-resolution">Proposed resolution</h3>
Investigate recursion limit in paragraph rendering.

<h3 id="summary-remaining-tasks">Remaining tasks</h3>
- [ ] Confirm reproduction
- [ ] Investigate root cause
- [ ] Implement fix
- [ ] Add test

<h3 id="summary-ui-changes">User interface changes</h3>
None

<h3 id="summary-api-changes">API changes</h3>
None

<h3 id="summary-data-model-changes">Data model changes</h3>
None

Example 2: Feature Request

User: "I want to suggest adding a feature to export paragraphs"

Title: Add ability to export paragraph configurations as YAML

<h3 id="summary-problem-motivation">Problem/Motivation</h3>
Developers need to share paragraph type configurations between sites. Currently, this requires manually recreating configurations or using Features module.

<h3 id="summary-proposed-resolution">Proposed resolution</h3>
Add a "Export" tab to paragraph types that generates YAML configuration that can be imported via drush or admin UI.

<h3 id="summary-remaining-tasks">Remaining tasks</h3>
- [ ] Design export format
- [ ] Implement export functionality
- [ ] Add import functionality
- [ ] Add drush commands
- [ ] Document workflow

<h3 id="summary-ui-changes">User interface changes</h3>
- New "Export" tab on paragraph type edit page
- YAML textarea with copy button
- Import form at /admin/structure/paragraphs/import

<h3 id="summary-api-changes">API changes</h3>
- New service: paragraphs.config_exporter
- New drush command: paragraphs:export

<h3 id="summary-data-model-changes">Data model changes</h3>
None

Example 3: Quick Status Update

User: "How do I mark my issue as ready for review?"

Status changes:
1. Go to your issue page
2. Scroll to the status field (usually near bottom)
3. Change from "Active" or "Needs work" to "Needs review"
4. Add a comment explaining what's ready for review
5. Click Save

Best practice: Include a summary of changes in your comment when changing to "Needs review".

Example 4: Contributing a Local Fix

User: "I fixed a PHP 8.2 deprecation warning in the webform module. How do I contribute this back?"

Response:
Great! Here's how to contribute your fix:

1. **Create an issue** (if one doesn't exist):
   /drupal-issue create webform

   Use this title format: "PHP 8.2 deprecation warning in [ClassName]"
   Category: Bug report
   Priority: Normal (or Major if it causes errors)

2. **Create a merge request**:
   /drupal-mr webform {issue_number}

   This clones the project and sets up your branch.

3. **Apply your fix**:
   cd ~/.cache/drupal-contrib/webform
   # Copy your fixed file or apply your patch
   git add .
   git commit -m "Issue #{issue_number}: Fix PHP 8.2 deprecation warning in ClassName"
   git push webform-{issue_number} {branch_name}

4. **Complete the MR** in your browser when the URL opens.

5. **Update issue status** to "Needs review" on drupal.org.

Tip: In your issue description, include the exact deprecation warning message
and the PHP/Drupal versions where you tested the fix.

Example 5: Already Have a Patch File

User: "I have a .patch file that fixes an issue. How do I submit it?"

Response:
Modern drupal.org workflow uses merge requests instead of patch files, but you can
still apply your patch:

1. **Create or find the issue** on drupal.org for your fix

2. **Set up the MR environment**:
   /drupal-mr {project} {issue_number}

3. **Apply your patch**:
   cd ~/.cache/drupal-contrib/{project}
   git apply /path/to/your/fix.patch

   If that fails, try:
   git apply --3way /path/to/your/fix.patch

4. **Commit and push**:
   git add .
   git commit -m "Issue #{issue_number}: Description of fix"
   git push {project}-{issue_number} {branch_name}

5. **Complete the MR** in browser.

Note: If you just want to share the patch without creating an MR, you can attach
the .patch file directly to the issue as a comment. However, merge requests are
preferred as they enable automated testing.

Common Mistakes to Avoid

1. No version info - Always include Drupal and module versions
2. No steps to reproduce - Bugs without repro steps often get closed
3. Duplicate issues - Search before creating
4. Wrong project - Make sure you're creating the issue on the correct project
5. Mixing issues - One issue per bug/feature
6. No follow-up - Respond to maintainer questions
7. Using Markdown instead of HTML - drupal.org expects HTML format
8. Submitting patches without an issue - Always create an issue first, then attach code
9. Using patches instead of MRs - Merge requests are preferred; they enable automated testing

Resources

• Drupal Issue Queue Documentation
• Issue Priority Guidelines
• Writing Good Bug Reports