contribution-setup

Contribution Setup (worker skill)

Onboarding for a Drupal contribution. Optional, idempotent, not a gate. Detect what already exists and do only what is missing — a contributor who arrives with a ready environment can skip straight to issue.

Backs /drupal-ai-contrib:setup. Load the knowledge layer via dev-guides-navigator: drupal/contributing/ddev-contribution-environment, drupal/contributing/contrib-project-scaffolding, drupal/contributing/three-contribution-workflows-compared, drupal/contributing-with-ai/ai-toolchain-for-contribution.

Procedure

1. Detect the workflow and issue system

Determine — by inspecting the working directory and asking the contributor only what cannot be inferred:

• Workflow — core / your own contrib / someone else's contrib (the three workflows differ in authority, CI ownership, who merges). See the workflows dev-guide.
• Issue system — drupal.org classic queue vs. GitLab. Detect by following the project's Issues link; do not assume.

2. Detect the environment

Check for an existing DDEV project (.ddev/config.yaml) and the add-on in use. If a working contribution environment already exists, report it and stop — nothing to do.

If none exists, stand up DDEV with the workflow-matched add-on:

Workflow	Add-on
Single contrib module/theme	ddev-drupal-contrib (module repo is the project root; web/ + vendor/ generated & gitignored)
Multi-module suite	ddev-drupal-suite
Drupal core	ddev-drupal-core-dev

3. Resolve the gate config — two modes

Existing module — discover gates by parsing .gitlab-ci.yml:

• Read the gitlab_templates include and ref, the variables: block (_TARGET_CORE, _TARGET_PHP, _GITLAB_TEMPLATES_REF, _PHPUNIT_CONCURRENT, SKIP_*, OPT_IN_TEST_*).
• Record the discovered gate set; verify will mirror exactly these.

New module / maintainer setup — scaffold the correct config (writes — see §Writes). Generate, version-resolved per the target core, from the scaffolding dev-guide:

• .gitlab-ci.yml — the gitlab_templates include + a variables: block
• phpcs.xml.dist — Drupal + DrupalPractice, scoped to src + tests
• phpstan.neon — phpstan-drupal extension, the project's level
• phpunit.xml.dist — the major-version-correct schema (D11 → PHPUnit 11 schema, <source> block, failOnWarning; D10 → PHPUnit 9.x schema + DrupalListener) — copy from the target core, never hand-write the version
• .cspell-project-words.txt
• drupal/core-dev (+ drupal/coder, phpstan/phpstan, mglaman/phpstan-drupal) in require-dev, constrained to the target major

4. Ensure the toolchain

Drupal AI skills — ensure ai_best_practices and ai_skills are installed via drupal_devkit (the cross-harness skill installer). If drupal_devkit is absent, report how to obtain it; do not block.

The issue / MR CLI — the issue, submit, and pipeline skills wrap mglaman/drupalorg-cli. Detect it with command -v drupalorg (the executable is drupalorg, not drupalorg-cli). If it is missing, surface the install instructions from ${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md — that reference covers what the tool is, the recommended PHAR install, the deprecated Composer path, and the subcommand set. Offer to install it; do not block if the contributor declines (issue/submit re-surface the same instructions).

The GitLab CLI (glab) — authenticated GitLab writes on migrated projects (fork push, MR create/update, pipeline status) are delegated to the drupal-gitlab skill, which drives glab against git.drupalcode.org. The drupal-gitlab skill itself ships with ai_best_practices (installed above via drupal_devkit) — no install step for the skill — but glab is a separate binary. Detect and report it:

command -v glab                                  # installed?
glab auth status --hostname git.drupalcode.org   # authenticated for Drupal's GitLab?

If glab is missing or not authenticated, surface the next step — install glab, then glab auth login --hostname git.drupalcode.org (a write-capable token is needed only for pushes / MR creation; reads work read-only — see the drupal-gitlab README for token scopes). Soft posture, exactly like the drupalorg check: report the gap, never block. The legacy drupalorg reads still work without glab; only migrated-project authenticated writes need it.

5. Check contribution credentials — and guide, do not assume

The contribution arc needs the contributor's drupal.org credentials for its write operations. Surface this now — do not let it surface mid-issue as a failed git push. The plugin and the CLI cannot set credentials up; this is the contributor's own account action. Guide them through it.

• Read operations (drupalorg issue:show, mr:list, project:issues) hit public APIs — no credentials needed. An empty project:issues result can itself be an auth/config gap rather than "no issues" — note that when reporting.
• Write / push operations — git push to an issue fork, and the /do: issue-bot commands — need an SSH key registered on the contributor's drupal.org account, because issue-fork git remotes use SSH URLs ([email protected]:…).

Detect, then guide:

ssh -T [email protected]      # a working key greets the contributor by username

If it does not authenticate, tell the contributor plainly: this is a ~2-minute action — register an SSH key at drupal.org → My account → SSH keys (add the public key, e.g. ~/.ssh/id_ed25519.pub). It is the prerequisite for git push to issue forks; without it, issue can still review and read, but cannot push a branch. Never block setup on it — report it as the next thing to do. See ${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md §Authentication.

6. Environment-match

Install the CI-target core version + drupal/core-dev so phpunit / phpstan resolve to the same releases CI uses (the local DDEV default usually will not match). This is the mechanism that makes verify's gates trustworthy — see contribution-verify.

7. Report

Summarize, and for each item state ready vs. needs-action so the contributor knows their exact next step: workflow, issue system, environment status, the resolved gate set, AI-skill status, the issue/MR CLI (drupalorg) status, the GitLab CLI (glab) status (installed + authenticated for git.drupalcode.org), the credentials/SSH-key status, the environment-match result. Point the contributor at issue (or, if work is underway, verify) — and if the SSH key is missing, name that as the first step.

Writes — explicit confirmation only

setup writes files only with explicit user confirmation and only within the target project. Show the contributor each file to be written before writing it. Never write outside the project directory.

Detect-driven

Every step checks first and does only what is missing. Re-running setup on a ready environment is a no-op that simply reports state.

Examples

Example 1: existing module, environment ready

Trigger: /drupal-ai-contrib:setup in a contrib module that already has DDEV. Actions:

1. Detect the workflow (someone else's contrib) and the GitLab issue system.
2. DDEV already present → report it, do not re-create.
3. Parse .gitlab-ci.yml, record the discovered gate set; environment-match the core. Result: No files written; the contributor is told to proceed to issue.

Example 2: new module, maintainer setup

Trigger: /drupal-ai-contrib:setup in a fresh contrib module with no CI config. Actions:

1. Stand up DDEV with ddev-drupal-contrib.
2. Show each scaffold file (.gitlab-ci.yml, phpcs.xml.dist, phpstan.neon, phpunit.xml.dist, .cspell-project-words.txt) and write only on confirmation. Result: A CI-ready module the maintainer owns.

Troubleshooting

Situation	Handling
drupal_devkit not installed	Report how to obtain it; do not block setup.
drupalorg not on PATH	Surface references/drupalorg-cli.md (PHAR install); offer to install; do not block. If installed via Composer global, the bin dir may just be off PATH — see the reference's Install note.
glab missing or not authenticated	Report it as a next step (install glab; glab auth login --hostname git.drupalcode.org); never block. Only migrated-project authenticated writes need it — drupalorg reads and the legacy queue work without it. See references/drupalorg-cli.md §Hybrid model.
No SSH key registered on the drupal.org account	Guide the contributor to add one (drupal.org → My account → SSH keys); report it as the next step. Read/review still works; git push to issue forks does not. Never block.
Workflow cannot be inferred	Ask the contributor — never assume core vs. contrib.
.gitlab-ci.yml exists but uses a non-gitlab_templates setup	Record what is there; verify mirrors the discovered jobs as-is.
Contributor declines a scaffold write	Skip that file; report which gates remain unconfigured.