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 patches in `patches/`.
Maintainer Burnout: Spammy, low-quality issues.	Maintainer-friendly: Warns on risky patterns and keeps human review in the loop.
Lost Fixes: Local patches vanish on `composer update`.	Preserved Work: Artifacts are saved for future rerolls.
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 patch files only
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 new patch 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 PATCH]
    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
│   └── patches/
│       └── metatag-fix-3345678.patch  # Upload this to the issue
└── unfiled-update-module-check/       # New issue needed
    ├── REPORT.md
    ├── ISSUE_COMMENT.md
    └── patches/
        └── project-fix-new.patch

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

Installation

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

Usage

Search only (preflight):

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

Search + generate patch:

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 patch: TypeError in MetatagManager" \
    "After patch: Page renders without error" \
  --out .drupal-contribute-fix

Test an existing MR/patch (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:

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 the existing MR
Patch-based	Issue uses patch workflow	Reroll/update existing patches
New	No existing fixes	Submit your patch

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 patch 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 patches when existing upstream fixes are found:

Outcome	Action	Exit
✅ PROCEED	Patch generated. Ready to contribute.	`0`
🛑 REDIRECT	Existing fix found. Use the upstream MR/patch.	`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 create Composer patch for any drupal/* package

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; writing a patch takes 30 minutes
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 how to submit upstream

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 fixed the bug locally. Here's how to contribute it upstream:

📁 .drupal-contribute-fix/<nid>-<slug>/
  - ISSUE_COMMENT.md - Copy/paste this to drupal.org
  - patches/<file>.patch - Upload to the issue

Steps:
1. Go to https://www.drupal.org/node/<nid>
2. Paste content from ISSUE_COMMENT.md
3. Attach the patch file
4. Set status to "Needs review"

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

Create a new issue at https://www.drupal.org/project/issues/
Use ISSUE_COMMENT.md as the description template
Attach the patch file

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Usage

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

Uh oh!

Releases

Packages

Languages

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

License

zivtech/drupal-contribute-fix

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

Usage

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

Languages

Packages