drupalorg-issue-helper

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