drupal-contribute-fix

Turn local Drupal fixes into effortless, maintainer-friendly contributions.

AI scales code generation, but it shouldn't scale noise.

We want to empower AI Agents to fix Drupal bugs, while protecting maintainers from a flood of duplicate or low-quality contributions. This tool bridges the gap, transforming the Agent from a "local hacker" into a responsible open-source contributor.

Our Mission: High Signal, Zero Noise

To ensure contributions are helpful rather than overwhelming, this skill enforces three strict rules:

Targeted: Searches Drupal.org first. If a fix exists, we stop and recommend using it. No duplicate effort.
High-Quality: Runs PHP lint by default; runs PHPCS if available; flags hack patterns.
Maintainer-First: Never auto-posts. Generates clean artifacts for you to review.

Why Use This?

Stop your AI from "hacking" core.

❌ Without this Skill	✅ With `drupal-contribute-fix`
Duplicate Work: Agent ignores existing MRs/patches.	Upstream-aware: Searches Drupal.org and surfaces existing fixes.
Tech Debt: Fixes are buried in `vendor/` or `core/`.	Standardized: Generates local `.diff` review artifacts in `diffs/`.
Maintainer Burnout: Spammy, low-quality issues.	Maintainer-friendly: Warns on risky patterns and keeps human review in the loop.
Lost Fixes: Local work vanishes on `composer update`.	Preserved Work: Artifacts are saved for future MR follow-up.
No Validation: Errors slip through.	Quality Gates: Runs PHP lint and PHPCS (if available).

What This Will NOT Do

This skill is designed to be helpful without creating churn.

🚫 Never	✅ Instead
Auto-post to Drupal.org	Generates files for you to review and paste
Create issues automatically	Searches existing issues; you decide what to file
Push to git.drupalcode.org	Outputs local artifacts only (comment + `.diff`)
Bypass your review	Every artifact requires human approval before submission
Spam maintainers	Stops when existing MR/patch found; encourages testing over duplicating

The "No Noise" Guarantee

This tool never auto-posts to Drupal.org or pushes code automatically. It only generates local artifacts for you to review and submit.

The --force flag should be rare. Use it only when:

You've reviewed the existing MR/patch and confirmed your fix is meaningfully different
You're providing a reroll for a different version
The existing fix doesn't apply to your Drupal version

When using --force, always explain in your issue comment why a local .diff artifact was needed.

How It Works

graph TD
    A[🔍 Local Fix Detected] --> B{Search Drupal.org}
    B -- MR/Patch Exists --> C[🛑 STOP & DOWNLOAD]
    C --> D[Test Existing Fix]
    B -- No Fix Found --> E{Check Dev Branch}
    E -- Fixed in Dev --> F[🛑 STOP & UPGRADE]
    E -- Bug Exists in Dev --> H{Hack Detection}
    H -- Clean Fix --> I[✅ GENERATE MR ARTIFACTS + DIFF]
    H -- Hacky Fix --> K[⚠️ WARN USER]

Note: Dev-branch checks are currently a manual step; the tool does not auto-verify them yet.

What You Get

.drupal-contribute-fix/
├── UPSTREAM_CANDIDATES.json           # Search results cache (shared)
├── 3345678-fix-metatag-build/         # Known issue with slug
│   ├── REPORT.md                      # Analysis & next steps
│   ├── ISSUE_COMMENT.md               # Copy/paste this to drupal.org
│   └── diffs/
│       └── metatag-fix-3345678.diff   # Local review artifact
└── unfiled-update-module-check/       # New issue needed
    ├── REPORT.md
    ├── ISSUE_COMMENT.md
    └── diffs/
        └── project-fix-new.diff

Directory naming: {nid}-{slug}/ for existing issues, unfiled-{slug}/ for new issues.

Quick Start

Prerequisites

Python 3.8+
Git
Internet access to drupal.org API
DDEV (recommended for running drupalorg-cli)
PHP 8.1+ in the runtime where drupalorg-cli executes

Installation

# Clone from your preferred location
git clone <repository-url>
cd drupal-contribute-fix

DDEV + drupalorg-cli Setup (Recommended)

This skill now recommends drupalorg-cli for issue-fork/MR/pipeline execution. If your host PHP is older, run drupalorg-cli inside DDEV.

Install a global DDEV command:

mkdir -p ~/.ddev/commands/web
cat > ~/.ddev/commands/web/drupalorg <<'EOF'
#!/usr/bin/env bash
## Description: Run drupalorg-cli inside the web container
## Usage: drupalorg [args]
## ProjectTypes: drupal,drupal11,drupal10,drupal9,drupal8,drupal7,backdrop,php
## ExecRaw: true
set -euo pipefail
PHAR="/mnt/ddev-global-cache/drupalorg-cli/drupalorg.phar"
URL="https://github.com/mglaman/drupalorg-cli/releases/latest/download/drupalorg.phar"
mkdir -p "$(dirname "$PHAR")"
if [ ! -x "$PHAR" ]; then
  curl -fsSL "$URL" -o "$PHAR"
  chmod +x "$PHAR"
fi
exec php "$PHAR" "$@"
EOF
chmod +x ~/.ddev/commands/web/drupalorg

Optional shell alias:

alias drupalorg='ddev drupalorg'

Verify in a DDEV project directory:

ddev restart
ddev drupalorg --version

Usage

Search only (preflight):

python3 scripts/contribute_fix.py preflight \
  --project metatag \
  --keywords "TypeError MetatagManager" \
  --out .drupal-contribute-fix

Tip: Drupal.org's api-d7 endpoint does not support a full-text text= filter (it returns HTTP 412). For manual keyword searching, use the Drupal.org UI search:

https://www.drupal.org/project/issues/search/<project>?text=<keywords>

Companion Tool: drupal-issue-queue (optional)

For deeper triage (filters by status/priority/category/version/component/tag) and issue/thread summaries via api-d7, use the companion tool drupal-issue-queue (GitHub repo: scottfalconer/drupal-issue-queue).

Common examples (run from the drupal-issue-queue directory):

# Summarize an issue (Markdown)
python scripts/dorg.py issue <nid-or-url> --format md

# Filter/search a project's issues
python scripts/dorg.py search --project <machine_name> --status "needs review" --limit 20 --format json

If drupal-contribute-fix can’t auto-detect drupal-issue-queue on your machine, set:

export DRUPAL_ISSUE_QUEUE_DIR=/path/to/drupal-issue-queue

Search + generate MR artifacts + local diff:

python3 scripts/contribute_fix.py package \
  --changed-path /path/to/drupal/web/modules/contrib/metatag \
  --keywords "TypeError MetatagManager" \
  --test-steps \
    "Enable Metatag module" \
    "Trigger the error in the UI" \
    "Before fix: TypeError in MetatagManager" \
    "After fix: Page renders without error" \
  --out .drupal-contribute-fix

Preferred handoff to drupalorg-cli (run in your Drupal project directory):

drupalorg issue:show <nid> --format=llm
drupalorg issue:get-fork <nid> --format=llm
drupalorg issue:setup-remote <nid>
drupalorg issue:checkout <nid> <branch>
drupalorg mr:list <nid> --format=llm
drupalorg mr:status <nid> <mr-iid> --format=llm

Test an existing MR/diff artifact (generate RTBC comment):

python3 scripts/contribute_fix.py test \
  --issue 3345678 \
  --tested-on "Drupal 10.2, PHP 8.2" \
  --result pass \
  --out .drupal-contribute-fix

Reroll an existing patch for your version (legacy fallback):

python3 scripts/contribute_fix.py reroll \
  --issue 3345678 \
  --patch-url "https://www.drupal.org/files/issues/metatag-fix-3345678-15.patch" \
  --target-ref 2.0.x \
  --out .drupal-contribute-fix

Workflow Modes

The skill understands Drupal's contribution workflow:

Mode	What It Means	Your Action
MR-based	Issue has active Merge Request	Review/update via `drupalorg mr:*` commands
Historical patches	Issue has patch attachments but no MR	Use MR workflow for new work
New	No existing fixes	File issue, then use `drupalorg` issue-fork + MR flow

Options

Option	Description
`--project`	Drupal project machine name (e.g., `metatag`, `drupal`)
`--keywords`	Error message fragments or search terms
`--changed-path`	Path to modified module/theme/core directory
`--issue`	Known issue number (runs gatekeeper against this issue)
`--force`	Override gatekeeper and generate local diff artifact anyway
`--offline`	Use cached data only
`--detect-deletions`	Include deleted files (risky with Composer trees)
`--test-steps`	Required for `package`. Specific reproduction/verification steps

Exit Codes (Gatekeeper Behavior)

The skill refuses to generate local artifacts when existing upstream fixes are found:

Outcome	Action	Exit
✅ PROCEED	MR artifacts + local diff generated.	`0`
🛑 REDIRECT	Existing fix found. Use the upstream MR workflow.	`10`
⚠️ REVIEW	Fix deemed too broad/hacky. Post analysis first.	`30`
⛔ ERROR	Network or detection failure.	`40`
🔒 SECURITY	Security issue detected. Follow security team process.	`50`

For AI Agent Developers

This skill follows the Agent Skills specification. The main skill definition is in SKILL.md.

MANDATORY Activation Rules

You MUST use this skill when ANY of these conditions are true:

Early Triggers (no stack trace needed):

User mentions module name + problem - "metatag has an error", "mcp isn't working", "webform bug"
Platform + module issue - "Acquia best practices" + any module problem
Explicit contrib mention - "contrib module", "drupal module"

Technical Triggers (after investigation):

Error originates FROM contrib/core - stack trace shows modules/contrib/, core/
About to edit contrib/core files - */modules/contrib/* or */core/*
About to convert local contrib/core changes into upstream MR work

Key: Don't wait for a stack trace. If user says "[module] has an error", trigger immediately.

Run preflight BEFORE writing any code - even for "local fixes".

This is NOT Just for "Upstream Contributions"

Common mistake: Treating this as an "optional" skill for when users want to contribute to drupal.org.

Correct usage: Use for ALL contrib/core fixes because:

The fix may already exist (don't duplicate work)
Preflight takes 30 seconds; reworking duplicate code takes far longer
Even "local fixes" should check upstream first

How to Recognize Contrib/Core Errors

# Error FROM contrib/core - USE THIS SKILL:
Drupal\metatag\MetatagManager->build()
docroot/modules/contrib/mcp/src/Plugin/...
web/core/lib/Drupal/Core/...

# Error in custom module - may not apply:
modules/custom/mymodule/src/...
(unless custom code triggers a bug in contrib/core)

Path Triggers

web/core/             docroot/core/
web/modules/contrib/  docroot/modules/contrib/
web/themes/contrib/   docroot/themes/contrib/
patches/drupal-*      patches/*/

Example: Correct Agent Behavior

User says: "I have the mcp module installed but it has an error with the update module not being installed, but Acquia best practices are for that to not be installed."

Agent should IMMEDIATELY recognize triggers:

"mcp module" → Drupal module name
"has an error" → problem indicator
"Acquia best practices" → platform constraint

This is THREE triggers in one sentence. Fire the skill FIRST, before investigating.

Agent should:

IMMEDIATELY invoke drupal-contribute-fix skill (don't investigate first!)
Run preflight --project mcp --keywords "update module not installed"
Check if fix already exists upstream
THEN proceed with local fix if needed
AFTER fixing: Run package to generate contribution artifacts
Tell user about .drupal-contribute-fix/ files and provide drupalorg-cli next commands

WRONG behavior: Reading code first, finding the bug, fixing it, THEN thinking "oh maybe I should check upstream". By then you've already duplicated work.

MANDATORY: After Fixing, Complete the Workflow

DO NOT just fix locally and move on. After making a local fix:

Run package to generate contribution artifacts
Preserve the .drupal-contribute-fix/ directory - NEVER delete it
Guide user through the submission process

Even if user asks to "reset" or "undo": Keep the contribution artifacts. The whole point is to help the Drupal community.

What To Tell Users When Done

I've completed triage/fix prep. Here's how to continue upstream:

📁 .drupal-contribute-fix/<nid>-<slug>/
  - ISSUE_COMMENT.md - Copy/paste this to drupal.org
  - diffs/<file>.diff - Local review artifact (do not upload unless maintainers ask)

Recommended commands:
drupalorg issue:show <nid> --format=llm
drupalorg issue:get-fork <nid> --format=llm
drupalorg issue:setup-remote <nid>
drupalorg issue:checkout <nid> <branch>
drupalorg mr:list <nid> --format=llm

For unfiled issues (unfiled-<slug>/):

Create a new issue at https://www.drupal.org/project/issues/
Use ISSUE_COMMENT.md as the description template
Continue with drupalorg commands using the new issue NID

Project Structure

drupal-contribute-fix/
├── SKILL.md              # Agent skill definition
├── README.md             # This file
├── LICENSE               # GPL-2.0-or-later
├── lib/                  # Python modules
│   ├── drupalorg_api.py  # Drupal.org API client
│   ├── issue_matcher.py  # Issue search and scoring
│   ├── baseline_repo.py  # Git baseline resolution
│   ├── patch_packager.py # Local diff generation
│   ├── report_writer.py  # Output file generation
│   ├── security_detector.py
│   └── validator.py
├── scripts/
│   └── contribute_fix.py # CLI entry point
├── references/           # Reference documentation
└── examples/             # Sample outputs

Contributing

Contributions are welcome! This skill is for the Drupal community.

Fork the repository
Create a feature branch
Make your changes
Run syntax checks: python3 -m py_compile scripts/contribute_fix.py lib/*.py
Submit a pull request

License

GPL-2.0-or-later - Compatible with Drupal's licensing.

Acknowledgments

Drupal Association for the drupal.org API
Agent Skills specification by Anthropic
The Drupal community for contribution workflow best practices

Built for the Drupal community to encourage proper upstream contribution.

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
examples		examples
lib		lib
references		references
scripts		scripts
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

drupal-contribute-fix

Our Mission: High Signal, Zero Noise

📖 Table of Contents

Why Use This?

What This Will NOT Do

The "No Noise" Guarantee

How It Works

What You Get

Quick Start

Prerequisites

Installation

DDEV + drupalorg-cli Setup (Recommended)

Usage

Companion Tool: drupal-issue-queue (optional)

Workflow Modes

Options

Exit Codes (Gatekeeper Behavior)

For AI Agent Developers

MANDATORY Activation Rules

Early Triggers (no stack trace needed):

Technical Triggers (after investigation):

This is NOT Just for "Upstream Contributions"

How to Recognize Contrib/Core Errors

Path Triggers

Example: Correct Agent Behavior

MANDATORY: After Fixing, Complete the Workflow

What To Tell Users When Done

Project Structure

Contributing

License

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages