docs: enforce bilingual plugin documentation parity

.github/pull_request_template.md

@@ -17,6 +17,8 @@ Closes #(issue number)
 ## Checklist
 
 - [ ] I have read the contribution guidelines
+- [ ] User-facing documentation changes include matching English and German updates
+- [ ] I ran `npm run check:docs`
 - [ ] I have verified links work correctly
 - [ ] Code examples are tested
 - [ ] Spelling and grammar checked

.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    name: Docs (Node.js ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [22, 24]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Set up Node.js
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+      - name: Check bilingual documentation
+        run: npm run check:docs
+      - name: Build docs
+        run: npm run build
+      - name: Validate site artifact
+        run: test -s dist/index.html
+
+  actionlint:
+    name: Validate GitHub Actions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Run actionlint
+        uses: reviewdog/action-actionlint@6fb7acc99f4a1008869fa8a0f09cfca740837d9d # v1.72.0

.github/workflows/deploy.yml

@@ -1,33 +1,47 @@
-name: Deploy to GitHub Pages
+name: Deploy to GitHub Pages
 
 on:
   push:
     branches:
       - main
   pull_request:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           node-version: 24
+          cache: npm
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
 
       - name: Install Playwright Chromium
         run: npx playwright install --with-deps chromium
 
+      - name: Check bilingual documentation
+        run: npm run check:docs
+
       - name: Build
         run: npm run build
 
+      - name: Validate Pages artifact
+        run: test -s dist/index.html
+
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
         with:
           path: ./dist
 
@@ -44,4 +58,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

README.md

@@ -11,6 +11,23 @@ npm run dev
 
 Visit `http://localhost:3000` to preview.
 
+## Contributing documentation
+
+User-facing documentation is maintained in English and German. Every page under
+`src/content/docs/` must be added or updated together with its counterpart under
+`src/content/docs/de/`, including Markdown plugin reference pages. Keep required
+frontmatter keys and internal links aligned, then run:
+
+```bash
+npm run check:docs
+```
+
+Locale-only exceptions are limited to intentional legal or local pages and must
+be documented with a reason in `scripts/docs-parity.config.mjs`.
+First-party plugin examples must use the canonical typed package name
+`@semrel/<plugin-type>-<name>`; legacy aliases belong only in explicitly
+allowlisted migration or deprecation context.
+
 ## Build
 
 ```bash
@@ -26,4 +43,3 @@ Deploys to GitHub Pages at `semrel.io` via GitHub Actions.
 - [Astro Documentation](https://docs.astro.build)
 - [Starlight Documentation](https://starlight.astro.build)
 - [semrel Repository](https://github.com/GoSemantics/semrel)
-

package.json

@@ -8,6 +8,9 @@
     "build": "astro build",
     "preview": "astro preview",
     "astro": "astro",
+    "docs:parity": "node scripts/check-docs-parity.mjs",
+    "test:docs": "node --test scripts/check-docs-parity.test.mjs",
+    "check:docs": "npm run test:docs && npm run docs:parity",
     "lighthouse": "node scripts/lighthouse-all.js",
     "lighthouse:build": "node scripts/lighthouse-all.js --build",
     "lighthouse:seo": "node scripts/lighthouse-all.js --build --categories seo,accessibility",

public/llms-full.txt

@@ -62,7 +62,7 @@ git log → Condition Plugin → Analyzer Plugin → SemVer Bump Decision
 tag_prefix: "v"
 
 plugins:
-  - uses: github           # provider
+  - uses: "@semrel/provider-github"  # provider
     name: github-release
     args:
       owner: MyOrg
@@ -191,8 +191,8 @@ linux/arm64, darwin/amd64, darwin/arm64, windows/amd64.
 ## Installing plugins
 
 ```bash
-semrel plugin install github          # installs provider-github
-semrel plugin install @semrel/slack   # installs hook-slack from the registry
+semrel plugin install @semrel/provider-github  # installs provider-github
+semrel plugin install @semrel/hook-slack       # installs hook-slack from the registry
 semrel plugin list                    # shows installed plugins
 semrel plugin restore                 # restores from .semrel.lock
 ```