## Goal Produce a **thin** `CONTRIBUTING.md` that carries only (a) a brief orientation to the contribution workflow and (b) the human/AI contribution policy — and **defers to the docs-site Contribution Standards page as the source of truth** for the mechanics: https://project.pages.drupalcode.org/groupsdrupalorg/contribution-standards/ **Merges #3578756** (the `/do:fork` workflow adoption) — that content is now part of what this work must cover; the full rationale + doc links are preserved in the closed #3578756. **Three deliverables** (see Part D): 1. A thin `CONTRIBUTING.md` at repo root — workflow pointer + AI policy. 2. A fleshed-out **and corrected** Contribution Standards docs page — the detailed mechanics live here, not in `CONTRIBUTING.md`. 3. An **agent-guidance file** (`CLAUDE.md` + `AGENTS.md`) — auto-loaded by AI coding tools, with the non-negotiable workflow guardrails inline. **Also folded into this MR (!12), scope addition:** standardize the toolchain on **Node 24 (LTS)** — `.nvmrc`, `docs/package.json` `engines>=24` + `engine-strict`, CI `node:24`, and the `developer-setup.md` node prerequisite. (Astro 7 requires node `>=22.12`; the old "node 20+" was stale.) ## Part A — Contribution workflow (merged from #3578756) - **Shared issue-fork model** — persists even for GitLab-native issues (we've left the d.o issue queue). *"There are no personal forks — contributors work together on a single shared issue fork per issue."* Create/join it with **`/do:fork`** as an issue comment (or DrupalBot's fork-management link). The fork is named `issue/groupsdrupalorg-<issue-number>`. - **Applies to everyone — including maintainers.** All issue work routes through the shared fork. Maintainer push access to canonical is *not* a licence to skip the fork for routine issue work; it exists for **merging MRs and trunk/release ops** only. "If you're on an issue, you're on a fork" — no maintainer exception. (This binds AI agents in a maintainer's session too: never take the direct-push-to-canonical shortcut just because access allows it.) - **Work in the fork:** branch, commit, open the MR in GitLab's native UI, target `1.x`, reference `Closes #NNNN`. Branch names are **`<issue-number>-<short-slug>`** off `1.x`; **no `feature/` prefix** (that idea is dropped — superseded by the shared-fork model). - **Merge authority:** merging into canonical needs a merge-capable role there (d.o "Write to VCS" → GitLab Developer, merges into unprotected `1.x`), which is separate from fork access. A fork contributor can push + open the MR but can't merge unless granted that role. Granting is self-service via drupal.org project → Maintainers. - **Fork lifecycle:** the fork is **not** deleted on merge — it persists per-issue and is eventually garbage-collected by drupal.org after the issue is closed. Deleting the MR source branch (a merge option) does not delete the fork. The merged squash commit lives in `1.x` regardless. Local cleanup (remove the fork remote + stale tracking branches) is on the contributor. - **Optional (not required):** a lightweight CI job flagging branches pushed *directly* to canonical that aren't trunk/release/legacy — a guard against accidental direct pushes. Low value under the shared-fork model; include only if convenient. (The stronger guard — protecting `1.x` so nobody, maintainers included, can push directly — is tracked in #3578760 as an infra ask.) ## Part A2 — Commit & MR-title conventions (GitLab-native squash-merge) - **Decision (confirmed):** this project **stays in GitLab** and merges via **GitLab-native squash-merge**, not the classic drupal.org merge-from-the-issue-page flow. - **Consequence:** the **MR title becomes the squash commit subject**, so the MR title must itself be a valid **Conventional Commit** — e.g. `task: #3578754 Bootstrap the Drupal 11.4 module` (types: `feat|fix|docs|ci|perf|refactor|test|task|revert`). This is *not* the classic `Issue #NNNN: Summary` style, which is only correct for the d.o issue-page merge path we are not using. - **Credit:** `By:` trailers (drupal.org usernames, no leading `@`) go in the MR description / squash-commit body; maintainers may also use `Co-authored-by:` / `Reported-by:` / `Reviewed-by:`. - **Reconcile the docs (do not just extend):** the current Contribution Standards page describes the **classic** merge (maintainer-drafted message, MR title cosmetic, "no self-merge"). That is **stale/incorrect** for our GitLab-native squash path and must be **corrected** as part of this work. Note also that existing `1.x` history uses the old `Issue #NNNN:` style — settle on Conventional Commits going forward and leave history as-is. ## Part B — Research the Drupal doc standard first Drupal.org has no single official CONTRIBUTING.md template (guidance is framed around README.md), so before writing, read and synthesize from: - https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or-distribution-project/documenting-your-project/readmemd-template - https://www.drupal.org/docs/develop/issues/issue-procedures-and-etiquette/issue-etiquette - A few CONTRIBUTING.md files from active, well-regarded contrib projects (no canonical template — synthesize from precedent). - Drupal core's AI-agent guidance discussion for context: https://www.drupal.org/project/drupal/issues/3568936 Post the sections/conventions you're adopting (and why) in this issue before finalizing. ## Part C — Research how other projects handle AI contributions Survey current (2026) policy approaches and summarize the range (strict bans: NetBSD, QEMU; restricted allow: Ghostty; disclosure-based: Kubernetes, OpenJDK; commit trailers like `Assisted-by:`). Maintained survey: https://github.com/melissawm/open-source-ai-contribution-policies . Bring back a short menu with tradeoffs, then propose (don't unilaterally decide) an approach. **DECIDED (2026-07-04):** AI-assisted contributions are welcome; a human reviews + merges every MR. **Disclosure = an MR-template checkbox that names the tool, plus an encouraged (not required) `Assisted-by: <tool>:<model>` commit trailer.** ## Part D — Deliverables ### D1 — `CONTRIBUTING.md` (thin) Keep it short. It should contain only: - A **few lines** orienting a newcomer to the shared issue-fork workflow (`/do:fork`, branch/MR to `1.x`), then a link to the Contribution Standards page for the detail. - The **human/AI policy** — the one thing that lives *in* `CONTRIBUTING.md` in full: AI-assisted contributions are welcome, but **every MR must be reviewed and pushed/merged by a human maintainer** (fixed policy; word it well using Part C's disclosure-style precedents), plus the required **disclosure mechanism** (DECIDED): an **MR-template checkbox** naming the AI tool + an **encouraged** `Assisted-by: <tool>:<model>` commit trailer. Ship `.gitlab/merge_request_templates/Default.md` carrying the checkbox. - A direct link to the Drupal Code of Conduct: https://www.drupal.org/dcoc - A prominent link to the Contribution Standards page: https://project.pages.drupalcode.org/groupsdrupalorg/contribution-standards/ ### D2 — Contribution Standards docs page (source of truth — flesh out **and correct**) The detailed mechanics live here, not in `CONTRIBUTING.md`. Must: - Cover the full workflow from **Part A** (shared fork, `/do:fork`, branch pattern, MR to `1.x`, merge authority, fork lifecycle, the no-maintainer-exception rule). - Cover **Part A2** (Conventional-Commit MR titles under squash-merge, `By:` trailers). - **Correct** the stale classic-merge description (see Part A2) — this is a fix, not just an addition. - Fold in the standard Drupal sections from **Part B** (issue process, coding standards, local setup/testing, how to submit an MR). ### D3 — Agent-guidance file (`CLAUDE.md` + `AGENTS.md`) Most devs drive contributions with AI (mostly Claude). Claude Code **auto-loads** a repo-root `CLAUDE.md`; it does **not** auto-load `CONTRIBUTING.md` or the docs site. So the critical guardrails must live in an auto-loaded file or bots won't see them. - Add a repo-root **`CLAUDE.md`** with the non-negotiables **inline** (not behind a link): 1. **Never push branches to canonical `origin` (`project/groupsdrupalorg`)** — trunk/release only, via merged MRs. **Applies even in a maintainer's session** (no bypass because access allows it). 2. **For any issue: `/do:fork` → work in the shared fork → MR to `1.x`** with a Conventional-Commit title. 3. **A human maintainer merges.** Bots never self-merge. Then link to the Contribution Standards page for the detail. - Add **`AGENTS.md`** (cross-tool convention for non-Claude agents) — **symlink to `CLAUDE.md`** so there is one file, two names, no drift. - Include a pre-commit **self-check** for the agent: `git remote get-url origin` → if it's `project/groupsdrupalorg`, STOP (you must be on an `issue/groupsdrupalorg-<n>` fork remote). - Include the concrete `/do:fork` recipe (post the comment via API → wait for DrupalBot → `git remote add issue git@git.drupal.org:issue/groupsdrupalorg-<n>.git` → branch/commit/push to the fork → open MR). ## Out of scope / tracked elsewhere - **Default branch → `1.x`: DONE.** Verified `default_branch=1.x`; `Closes #NNNN` auto-close on merge now works. (Was: self-service via GitLab → Settings → Repository → Branch defaults.) - **Protected `1.x` / push rules** (the hard guard that binds maintainers to fork→MR): tracked in **#3578760** as a drupal.org infra ask. - **GitLab Epics:** off for contrib; tracked in infra issue https://www.drupal.org/project/infrastructure/issues/3592968 . - Playbook copy-in is separate (#3578750). ## References - GitLab issues for Drupal.org projects: https://www.drupal.org/docs/develop/issues/gitlab-issues-for-drupalorg-projects - Creating issue forks: https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-drupal/creating-issue-forks - Drupal commit message standard (Conventional Commits): https://www.drupal.org/node/3586390 - Maintainer ↔ GitLab sync: https://www.drupal.org/drupalorg/blog/improvements-to-drupalorg-project-maintainers-syncing-with-gitlab-project-members