git:20260122.8e5cd0a to git:20260122.de995cf

137 added, 106 removed. Audit A to A.

---

name: drupalorg-issue-helper

description: Quick help with drupal.org issue templates, formatting, and best practices. Invoke when user asks "how do I write a bug report?", "drupal.org issue template", "issue formatting", or needs help structuring issue descriptions for drupal.org projects.

---

# Drupal.org Issue Helper

Quick assistance with drupal.org issue templates, formatting, 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

- ## Quick Auth Note

- **drupal.org has no write API** - issue creation requires browser automation.

+ ## Quick Note on Creating Issues

- **Save credentials for auto-login** (one-time setup):

- ```bash

- mkdir -p ~/.config/drupalorg

- cat > ~/.config/drupalorg/credentials.yml << 'EOF'

- username: your-username

- password: your-password

- EOF

- chmod 600 ~/.config/drupalorg/credentials.yml

- ```

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

- Then use `/drupal-issue create {project}` - the agent will auto-login if needed.

+ 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}`

+ ## Official drupal.org HTML Issue Template

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

+ ```html

+ <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

- ```markdown

- ## Problem/Motivation

+ Use this complete template for bug reports:

+ ```html

+ <h3 id="summary-problem-motivation">Problem/Motivation</h3>

{Clearly describe what's wrong. What did you expect to happen vs. what actually happened?}

- ## Steps to Reproduce

+ <h4 id="summary-steps-reproduce">Steps to reproduce</h4>

1. {First step - be specific}

2. {Second step}

3. {Third step}

4. {Observe the bug}

- ## Expected Behavior

- {What should happen when following the steps above?}

- ## Actual Behavior

- {What actually happens? Include any error messages.}

+ <h3 id="summary-proposed-resolution">Proposed resolution</h3>

+ {How should this be fixed?}

- ## Environment

+ <h3 id="summary-remaining-tasks">Remaining tasks</h3>

+ - [ ] Confirm the bug can be reproduced

+ - [ ] Write the fix

+ - [ ] Add test coverage

+ - [ ] Review and merge

- - **Drupal version**: 10.3.x

- - **Module version**: 2.0.x

- - **PHP version**: 8.2

- - **Web server**: Apache/Nginx

- - **Database**: MySQL 8.0 / MariaDB 10.x / PostgreSQL

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

+ None

- ## Additional Context

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

+ None

- {Screenshots, error logs, configuration details, etc.}

+ <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

- ```markdown

- ## Problem/Motivation

+ ```html

+ <h3 id="summary-problem-motivation">Problem/Motivation</h3>

{Why is this feature needed? What problem does it solve?}

- ## Proposed Resolution

+ <h3 id="summary-proposed-resolution">Proposed resolution</h3>

{How should this feature work? Be as specific as possible.}

- ## User Interface Changes

+ <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?}

- ## API Changes

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

{Any new hooks, services, or public methods?}

- ## Data Model Changes

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

{New database tables, fields, or configuration schema?}

- ## Alternatives Considered

- {What other approaches did you consider and why didn't you choose them?}

- ## Additional Context

- {Mockups, examples from other modules, user stories, etc.}

```

### 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

- ```markdown

- ## Summary

- {What needs to be done?}

- ## Detailed Description

+ ```html

+ <h3 id="summary-problem-motivation">Problem/Motivation</h3>

+ {What needs to be done and why?}

- {Provide more context and background}

+ <h3 id="summary-proposed-resolution">Proposed resolution</h3>

+ {Approach to completing the task}

- ## Acceptance Criteria

+ <h3 id="summary-remaining-tasks">Remaining tasks</h3>

+ - [ ] {Specific, testable task 1}

+ - [ ] {Specific, testable task 2}

+ - [ ] {Specific, testable task 3}

+ - [ ] Tests pass

+ - [ ] Documentation updated

- - [ ] {Specific, testable criterion}

- - [ ] {Another criterion}

- - [ ] {Tests pass}

- - [ ] {Documentation updated}

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

+ {If applicable, or "None"}

- ## Related Issues

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

+ {If applicable, or "None"}

- - #{related_issue_number}: {brief description}

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

+ {If applicable, or "None"}

```

## Support Request Template

- ```markdown

- ## What I'm Trying to Do

- {Describe your goal, not just your problem}

- ## What I've Tried

- 1. {First approach}

- 2. {Second approach}

- 3. {Third approach}

- ## Current Behavior

- {What's happening now?}

- ## Environment

+ ```html

+ <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}

- - Other relevant modules: {list}

+ - PHP version: {version}

- ## Code/Configuration

+ **What I've tried**:

+ 1. {Approach 1}

+ 2. {Approach 2}

- ```php

- // Relevant code snippet if applicable

- ```

+ <h3 id="summary-proposed-resolution">Proposed resolution</h3>

+ {What specific help or guidance do you need?}

- ## Screenshots

+ <h3 id="summary-remaining-tasks">Remaining tasks</h3>

+ - [ ] Get answer/guidance

+ - [ ] Implement solution

- {Attach if helpful}

+ <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

+ ```

- ## Problem/Motivation

+ ```html

+ <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.

- ## Steps to Reproduce

+ <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

- ## Expected Behavior

- Node saves successfully.

+ <h3 id="summary-proposed-resolution">Proposed resolution</h3>

+ Investigate recursion limit in paragraph rendering.

- ## Actual Behavior

- WSOD with error: "Maximum function nesting level of 256 reached"

+ <h3 id="summary-remaining-tasks">Remaining tasks</h3>

+ - [ ] Confirm reproduction

+ - [ ] Investigate root cause

+ - [ ] Implement fix

+ - [ ] Add test

- ## Environment

- - Drupal: 10.2.5

- - Paragraphs: 1.17

- - PHP: 8.2.15

+ <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

+ ```

- ## Problem/Motivation

+ ```html

+ <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.

- ## Proposed Resolution

+ <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.

- ## User Interface Changes

+ <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

- ## API Changes

- - New service: `paragraphs.config_exporter`

- - New drush command: `paragraphs:export`

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

+ - New service: paragraphs.config_exporter

+ - New drush command: paragraphs:export

- ## Alternatives Considered

- - Features module: Adds complexity for simple use case

- - Manual config sync: Error-prone and tedious

+ <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".

```

## 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

## Resources

- [Drupal Issue Queue Documentation](https://www.drupal.org/docs/develop/issues)

- [Issue Priority Guidelines](https://www.drupal.org/docs/develop/issues/issue-priorities)

- [Writing Good Bug Reports](https://www.drupal.org/docs/develop/issues/fields-and-other-parts-of-issues)