## Goal Bootstrap this repo as a **Drupal 11.4-compatible contrib module**: generate a **full** module scaffold, add the standard contrib files, add the module's **local** dev tooling (`require-dev`), and keep all development-only assets out of the packaged release. This is a **module-only repo** — contributors add it to their *existing* Drupal 11.4 site (which requires PHP 8.3+). The repo does **not** stand up a Drupal site. > **Scope note (2026-07-05) — shrunk to a bite-sized core.** Extracted to their own epic issues: > **CI test pipeline + static analysis + lefthook PHP checks → #3578771**; **Playwright browser > testing → #3578772**; **AI agent skills → #3578765**; **GitLab issue/MR templates → #3578766**. > This issue is now just: **scaffold + standard files + local dev tooling + packaging + "it installs".** > **Note:** `1.x` was started fresh (`c4884cf "Start 1.x trunk"`) — there are **no legacy Drupal 6 > files to remove** on this branch. The old `groupsorg.*` files live only on the `6.x-1.x` / > `7.x-1.x` branches. ### 0. Survey, inventory & baseline — BEFORE any changes Do NOT start scaffolding until you have inventoried what already works and captured a GREEN baseline. This repo already carries a working docs stack + hooks that the module work can silently break. Know good before you touch anything. **Inventory — everything currently in place that must keep working:** - Docs build: `cd docs && npm run build` (astro check + internal link validation + the Keystatic editability gate). - Docs dev server: `cd docs && npm run dev` starts; key pages render. - **Git hooks via lefthook** (adopted in #3578761): `lefthook install`; **pre-commit** runs `check:keystatic --staged`, **pre-push** runs the docs build — both block on failure. *(The legacy `.githooks` + `core.hooksPath=.githooks` pre-push mechanism was REMOVED in #3578761; lefthook now owns the single hooks path.)* - Docs CI pipeline (`.gitlab-ci.yml`): Pages job + external-link report. - Packaging: `git archive HEAD | tar -t` excludes `docs/` and `.gitlab-ci.yml` (export-ignore). - Pages site live: https://project.pages.drupalcode.org/groupsdrupalorg/ (200 over HTTPS). - DDEV loop: module visible at `web/modules/custom/groupsdrupalorg`; `ddev exec vendor/bin/phpunit --version` + PHPCS `Drupal,DrupalPractice` work. **Baseline:** run each item, record PASS/FAIL. Proceed only from a known-good baseline. ### 1. Scaffold the module (full skeleton) with `drush generate` Use Drush's code generator (the modern replacement for Drupal Console's `drupal generate:module`), powered by `chi-teck/drupal-code-generator`: ``` drush generate module ``` Run it inside a **Drupal 11.4 site you already have** (`drush generate` needs a Drupal root; `vendor/bin/dcg module` is the standalone equivalent). Produce a **full scaffold**, not just an `.info.yml`: > **Machine name = `groupsdrupalorg`.** drupal.org requires the module's machine name to equal > the project slug, and the DDEV mount path (`web/modules/custom/groupsdrupalorg`) depends on it — > so the files are `groupsdrupalorg.info.yml`, `groupsdrupalorg.module`, and `composer.json` > `name: drupal/groupsdrupalorg`. (The `<machine>` placeholders below all resolve to that.) - `<machine>.info.yml` — `name`, `type: module`, `package`, `description`, `core_version_requirement: ^11`. **Do not hardcode `version:` or `project:`** — drupal.org's packaging injects them; a hardcoded `version:` triggers a packaging warning. - `<machine>.module` — with a `hook_help()` stub. - **`composer.json`** — `type: drupal-module`, `name: drupal/<machine>`, a real `description`, `license: GPL-2.0-or-later`. - `src/` — PSR-4 autoloading configured. - `tests/src/` — Unit / Kernel / Functional skeletons. - Routing / permissions / services YAML for the pieces we know we'll need. Verify the generated `.info.yml` and `composer.json` against the values above (generator defaults may need tweaking for D11 + drupal.org conventions). _Design source:_ [drush generate](https://www.drush.org/12.x/commands/generate/) · the Drupal Code Generator (`chi-teck/drupal-code-generator`). ### 2. License Drupal contrib is **GPL-2.0-or-later**. drupal.org's packaging auto-adds `LICENSE.txt` to release tarballs, so it isn't strictly required in-repo — but if the scaffold doesn't include one, add the current GPL-2.0 `LICENSE.txt` and declare `"license": "GPL-2.0-or-later"` in `composer.json`. ### 3. README + standard contrib files Create a modern Drupal `README.md` (drupal.org moved from `README.txt` to `README.md`) with the standard sections: Introduction, Requirements, Installation, Configuration, Troubleshooting/FAQ, Maintainers. Add the standard contrib metadata files the flagship AI module also ships: - **`MAINTAINERS.txt`** — the drupal.org maintainer-list file (distinct from the README section). - **`SECURITY.md`** — point at drupal.org's [Security Team process](https://www.drupal.org/docs/develop/security-team) and state coverage status (opt-in for security advisory coverage once stable). - **`CHANGELOG.md`** — human-readable release notes. - **`.editorconfig`** — editor defaults matching Drupal coding standards; copy [Drupal core's](https://git.drupalcode.org/project/drupal/-/blob/11.x/.editorconfig) if the scaffold doesn't provide one. _Design source:_ [drupal.org README.md template](https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or-distribution-project/documenting-your-project/readmemd-template) · [`project/ai` repo root](https://git.drupalcode.org/project/ai/-/tree/1.x). ### 4. Local dev tooling (`require-dev`) — CI pipeline moved to #3578771 The **CI test pipeline** (drupalci GitLab templates running PHPCS/PHPStan/PHPUnit), the static-analysis config (`phpcs.xml.dist`/`phpstan.neon`), and **filling the lefthook PHP-check stubs** (`TODO(#3578754)` left in `lefthook.yml` by #3578761) are all tracked in **#3578771**. This issue keeps only what makes the scaffold **self-validating locally** — add to `composer.json` **`require-dev`** so a plain `composer install` gives the local tooling: - `drupal/core-dev` — PHPUnit + the core test scaffolding. - `drupal/coder` (+ `dealerdirect/phpcodesniffer-composer-installer`) — the `Drupal`/`DrupalPractice` PHPCS sniffs. - `mglaman/phpstan-drupal` (+ `phpstan/phpstan`) — Drupal-aware static analysis. - **`config.allow-plugins`** in `composer.json` must list the plugin packages (at least `dealerdirect/phpcodesniffer-composer-installer`, plus any `drupal/core-*` scaffold plugins and `phpstan/extension-installer` if used). Composer 2 **refuses to run unlisted plugins**, which is a *hard failure* under `--no-interaction` (i.e. in CI) — not just a prompt. The scaffold must be **phpcs-clean** (`Drupal,DrupalPractice`) and its **PHPUnit skeleton runs green locally**. Do **not** add `phpro/grumphp` — lefthook is the sole hook manager (#3578761, option 3a); the PHP checks are wired into it in #3578771. ### 5. Playwright browser testing — moved to #3578772 Browser/E2E testing (aligning with core's Nightwatch→Playwright move) is tracked in **#3578772**. Premature here — the module has no UI yet. **Packaging note stays here:** its `node_modules/` is dev-only (§7/§8). ### 6. AI agent skills — moved to #3578765 `.agents/skills/<name>/SKILL.md` authoring is tracked in **#3578765**. **Packaging stays here:** the `.agents/skills/` directory **ships** (no `export-ignore`) per §7. ### 7. Packaging — what ships vs. what doesn't Drupal has **no dist-folder build step**. drupal.org builds release tarballs with **`git archive`**, which honors **`.gitattributes export-ignore`**. Development-only assets stay in the repo (and every clone) but are stripped from the package: - **Ships (module):** `.info.yml`, `.module`, `src/`, `tests/`, `config/`, `composer.json`, `README.md`, `LICENSE.txt`, `MAINTAINERS.txt`, `SECURITY.md`, `CHANGELOG.md`, `.editorconfig`, and `.agents/skills/` (per #3578765). - **`export-ignore` (dev-only):** `docs/` (Starlight docs), `.gitlab-ci.yml`, the vendored **`playbook/`** directory (added in #3578750), **`lefthook.yml`** — and consider `.gitignore` / `.gitattributes` themselves. *(The old `.githooks/` is gone — removed in #3578761 — so it's no longer in this list.)* Verify with `git archive HEAD | tar -t` — only module files should appear. _Design source:_ drupal.org packages via git-archive / export-ignore — [Drupal core #3067979](https://www.drupal.org/project/drupal/issues/3067979). ### 8. Module `.gitignore` Add a small module `.gitignore` for the module's **own** local tooling output — `vendor/` (from `composer install` of the module's dev deps) and `node_modules/` (from Playwright, once #3578772 lands). Nothing site-related; this repo is module-only. ### 9. Regression pass — re-run the full §0 inventory (do LAST) After the work, re-run EVERY §0 inventory item and confirm nothing that worked before is broken. Special attention to the shared lefthook hooks path: - **lefthook still owns the single `core.hooksPath`** and the docs/Keystatic checks still fire (pre-commit `check:keystatic --staged`, pre-push docs build). Adding `require-dev` + scaffold files must not disturb the lefthook setup. *(The module PHP checks themselves are ADDED in #3578771, not here.)* - Docs build + internal link validation still GREEN; Pages still deploys. - Packaging: `git archive HEAD | tar -t` still module-only (docs + dev assets excluded). ### Housekeeping / done-when - `.info.yml` `core_version_requirement: ^11` (targeting 11.4). - Full scaffold present: `.info.yml`, `.module`, `composer.json`, `src/`, `tests/`, `README.md`, `LICENSE.txt`, `MAINTAINERS.txt`, `SECURITY.md`, `CHANGELOG.md`, `.editorconfig`. - `require-dev` includes the local tooling so checks + tests run on a plain `composer install`; the scaffold is **phpcs-clean** and the **PHPUnit skeleton runs green locally**. - **Module installs & enables in a running Drupal 11.4 site** (not just "files exist"): `ddev drush pm:install groupsdrupalorg` succeeds with no errors, `ddev drush pm:list` shows it **Enabled**, `ddev drush pm:uninstall groupsdrupalorg` is clean. Run in your local Drupal 11.4 DDEV site, against the module at `web/modules/custom/groupsdrupalorg` (the DDEV holding-site path is developer-specific — don't hardcode it). - `git archive` output is module-only (dev assets `export-ignore`d). - §0 baseline inventory re-verified GREEN after the work (§9) — no regressions in docs build, the lefthook hooks, packaging, or Pages. - **Deferred to follow-ups:** CI test pipeline → #3578771 · Playwright → #3578772.