/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 versi