From 050d496e554d695f8a43f22f4c0ca1353fc829fa Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 20 Sep 2026 08:44:32 -0400 Subject: [PATCH 1/8] CONTRIBUTING: point at the Docsy homes for CLA, merge gates, and scanning - The CLA, merge requirements, and workflow-security facts are project policy homed in docsy.dev's contributing page and maintainer notes; this file linked the Google CLA and carried twin sections that had already drifted - Links target the `main` branch deploy, which reflects the notes as they are; production lags at the release baseline - The one repo-specific fact, this repo's `main` ruleset, stays in the pointer --- CONTRIBUTING.md | 55 +++++++++++-------------------------------------- 1 file changed, 12 insertions(+), 43 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73ba1879f9..ddbbe8c7ef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,15 +5,8 @@ just a few small guidelines you need to follow. ## Contributor License Agreement -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. +Contributions require the same CLA as Docsy itself: see [Contributor License +Agreement][cla] in the Docsy contribution guidelines. ## Code reviews @@ -115,48 +108,24 @@ watches it, so theme edits hot-reload. ### Merge requirements -`main` is protected by a repository ruleset: changes land only through pull -requests, with linear history, no force pushes or deletions. A PR needs one -approving review from a member of the `docsy/maintainers` team, and its zizmor -analysis must be clean at the ruleset's thresholds (see -[Workflow security analysis](#workflow-security-analysis)). Maintainers (the -Maintain role or higher) can bypass the review requirement for a PR through -**Bypass rules and merge** (`gh pr merge --admin`); the bypass is logged in the -ruleset's insights. +Same as for Docsy ([Merge requirements][] in the maintainer notes), enforced by +this repo's [main ruleset][]. ### Workflow security analysis -`.github/workflows/zizmor.yaml` runs [zizmor][] over this repo's workflows in -its pedantic persona (security audits plus workflow hygiene) on every PR, on -pushes to `main`, and weekly, so the online audits catch advisories published -against already-pinned actions. Results upload to the repository's Security tab -as code-scanning alerts. - -- The job passes whatever it finds; findings are alerts to triage. Blocking - comes from the `main` ruleset's code-scanning rule: a security alert of high - or higher severity, or an error-level alert, on the PR's changed lines. -- The workflow calls the [OpenTelemetry shared workflow][otel-zizmor] at a - pinned commit; that workflow pins the zizmor action, which pins the zizmor - image by digest, so the scanner moves only when the pin here does. Review the - chain at each bump. -- CI-only by design: the repo carries no tooling dependency for it. For a local - run, with `GH_TOKEN` set for the online audits, where _`VERSION`_ is the - zizmor version the workflow's latest run logs (its `zizmor vX.Y.Z` banner): - - ```bash - uvx zizmor@VERSION --persona=pedantic . - ``` - -- `security-events: write` sits alone in this workflow, away from the job that - installs and builds. +Same as for Docsy: see [Workflow security analysis][] in the maintainer notes. [alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys +[cla]: + https://main--docsydocs.netlify.app/docs/contributing/#contributor-license-agreement [deploys]: https://app.netlify.com/sites/docsy-example/deploys [Docsy]: https://github.com/google/docsy [hugo-extended]: https://www.npmjs.com/package/hugo-extended [Hugo workspace]: https://gohugo.io/configuration/module/#top-level-settings -[otel-zizmor]: - https://github.com/open-telemetry/shared-workflows/blob/main/zizmor/README.md -[zizmor]: https://docs.zizmor.sh/ +[main ruleset]: https://github.com/docsy/docsy-example/rules/23697395 +[Merge requirements]: + https://main--docsydocs.netlify.app/project/about/maintainer-notes/#merge-requirements +[Workflow security analysis]: + https://main--docsydocs.netlify.app/project/about/maintainer-notes/#workflow-security-analysis From e0bd7281908c977b99768312196d57cac8095f95 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 20 Sep 2026 08:44:32 -0400 Subject: [PATCH 2/8] CONTRIBUTING: Docsy repo link follows the org move --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddbbe8c7ef..606ec00696 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -119,7 +119,7 @@ Same as for Docsy: see [Workflow security analysis][] in the maintainer notes. [cla]: https://main--docsydocs.netlify.app/docs/contributing/#contributor-license-agreement [deploys]: https://app.netlify.com/sites/docsy-example/deploys -[Docsy]: https://github.com/google/docsy +[Docsy]: https://github.com/docsy/docsy [hugo-extended]: https://www.npmjs.com/package/hugo-extended [Hugo workspace]: https://gohugo.io/configuration/module/#top-level-settings [main ruleset]: https://github.com/docsy/docsy-example/rules/23697395 From 5818bf84c6529327cbe271e1cfccc2e335edaf20 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 20 Sep 2026 08:56:34 -0400 Subject: [PATCH 3/8] CONTRIBUTING: route the code-review section too; purpose-first pointers - Drops the repository-ruleset attribution from the merge-requirements pointer: the EasyCLA gate is the org ruleset's - Guards the definition block from prettier wrapping Review round 1 (F1, F2, F4, F5). --- CONTRIBUTING.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 606ec00696..7d1cf6681e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,10 +10,8 @@ Agreement][cla] in the Docsy contribution guidelines. ## Code reviews -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. +For code-review requirements, see the [Docsy contribution +guidelines][code-reviews]. ## Community Guidelines @@ -108,24 +106,25 @@ watches it, so theme edits hot-reload. ### Merge requirements -Same as for Docsy ([Merge requirements][] in the maintainer notes), enforced by +For merge requirements, see the [Docsy maintainer notes][Merge requirements] and this repo's [main ruleset][]. ### Workflow security analysis -Same as for Docsy: see [Workflow security analysis][] in the maintainer notes. +For workflow security analysis, see the [Docsy maintainer +notes][Workflow security analysis]. + [alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys -[cla]: - https://main--docsydocs.netlify.app/docs/contributing/#contributor-license-agreement +[cla]: https://main--docsydocs.netlify.app/docs/contributing/#contributor-license-agreement +[code-reviews]: https://main--docsydocs.netlify.app/docs/contributing/#code-reviews [deploys]: https://app.netlify.com/sites/docsy-example/deploys [Docsy]: https://github.com/docsy/docsy [hugo-extended]: https://www.npmjs.com/package/hugo-extended [Hugo workspace]: https://gohugo.io/configuration/module/#top-level-settings [main ruleset]: https://github.com/docsy/docsy-example/rules/23697395 -[Merge requirements]: - https://main--docsydocs.netlify.app/project/about/maintainer-notes/#merge-requirements -[Workflow security analysis]: - https://main--docsydocs.netlify.app/project/about/maintainer-notes/#workflow-security-analysis +[Merge requirements]: https://main--docsydocs.netlify.app/project/about/maintainer-notes/#merge-requirements +[Workflow security analysis]: https://main--docsydocs.netlify.app/project/about/maintainer-notes/#workflow-security-analysis + From e336b34eff7cafa1f8ff43c26e3688c7220ef67c Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 20 Sep 2026 09:34:23 -0400 Subject: [PATCH 4/8] CONTRIBUTING: one pointer per audience - Folds the contributor sections into a single link to the contribution guidelines, and the two policy pointers into the Maintainer notes intro; the frame and the link targets carry the names the sentences repeated --- CONTRIBUTING.md | 36 ++++++------------------------------ 1 file changed, 6 insertions(+), 30 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d1cf6681e..3634d6d670 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,25 +1,12 @@ # How to Contribute -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. - -## Contributor License Agreement - -Contributions require the same CLA as Docsy itself: see [Contributor License -Agreement][cla] in the Docsy contribution guidelines. - -## Code reviews - -For code-review requirements, see the [Docsy contribution -guidelines][code-reviews]. - -## Community Guidelines - -This project follows -[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). +See the [contribution guidelines][]. ## Maintainer notes +[Merge requirements][] (enforced by the [main ruleset][]) and [workflow security +analysis][] are project-wide; the sections below are specific to this repo. + ### Dependency updates Renovate opens version-update PRs, created on Sundays, configured in @@ -104,27 +91,16 @@ npm run local -- serve The `local` prefix runs the script against the sibling Docsy, and the server watches it, so theme edits hot-reload. -### Merge requirements - -For merge requirements, see the [Docsy maintainer notes][Merge requirements] and -this repo's [main ruleset][]. - -### Workflow security analysis - -For workflow security analysis, see the [Docsy maintainer -notes][Workflow security analysis]. - [alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys -[cla]: https://main--docsydocs.netlify.app/docs/contributing/#contributor-license-agreement -[code-reviews]: https://main--docsydocs.netlify.app/docs/contributing/#code-reviews +[contribution guidelines]: https://main--docsydocs.netlify.app/docs/contributing/ [deploys]: https://app.netlify.com/sites/docsy-example/deploys [Docsy]: https://github.com/docsy/docsy [hugo-extended]: https://www.npmjs.com/package/hugo-extended [Hugo workspace]: https://gohugo.io/configuration/module/#top-level-settings [main ruleset]: https://github.com/docsy/docsy-example/rules/23697395 [Merge requirements]: https://main--docsydocs.netlify.app/project/about/maintainer-notes/#merge-requirements -[Workflow security analysis]: https://main--docsydocs.netlify.app/project/about/maintainer-notes/#workflow-security-analysis +[workflow security analysis]: https://main--docsydocs.netlify.app/project/about/maintainer-notes/#workflow-security-analysis From 21e0b2c8420b59b1d4ec6186884b8734b6dca295 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 20 Sep 2026 10:45:11 -0400 Subject: [PATCH 5/8] CONTRIBUTING: the ruleset mirrors Docsy's, it doesn't own the merge requirements - Re-applies r1 F1: the EasyCLA gate is the org ruleset's, so "enforced by the main ruleset" over-attributed --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3634d6d670..fd02127815 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,8 +4,9 @@ See the [contribution guidelines][]. ## Maintainer notes -[Merge requirements][] (enforced by the [main ruleset][]) and [workflow security -analysis][] are project-wide; the sections below are specific to this repo. +[Merge requirements][] and [workflow security analysis][] are project-wide (this +repo's [main ruleset][] mirrors Docsy's); the sections below are specific to +this repo. ### Dependency updates From b2a173c7d00a18aa46654ffea5d72b5b240de843 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 20 Sep 2026 11:22:27 -0400 Subject: [PATCH 6/8] CONTRIBUTING: drop the frame-pointing clause (r2.5) --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fd02127815..262bb39816 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,8 +5,7 @@ See the [contribution guidelines][]. ## Maintainer notes [Merge requirements][] and [workflow security analysis][] are project-wide (this -repo's [main ruleset][] mirrors Docsy's); the sections below are specific to -this repo. +repo's [main ruleset][] mirrors Docsy's). ### Dependency updates From 2a452212aeb9153b7aeb90f0118d87a3ef338216 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 20 Sep 2026 11:22:27 -0400 Subject: [PATCH 7/8] zizmor workflow: header comment follows the notes to their home - The CONTRIBUTING anchor it pointed at went with the section (r2.2); same target shape as docsy's workflow --- .github/workflows/zizmor.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/zizmor.yaml b/.github/workflows/zizmor.yaml index f41825cb00..1f4478df36 100644 --- a/.github/workflows/zizmor.yaml +++ b/.github/workflows/zizmor.yaml @@ -1,5 +1,5 @@ # Workflow security analysis with zizmor. Maintainer notes: -# CONTRIBUTING.md#workflow-security-analysis +# https://main--docsydocs.netlify.app/project/about/maintainer-notes/#workflow-security-analysis name: zizmor From 10e809ea9e128bec0d17d60a3d47b902b09c4a38 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 20 Sep 2026 11:22:27 -0400 Subject: [PATCH 8/8] README: Docsy repo link follows the org move (r2.3) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 39aed123b6..0995295b54 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ For build and preview problems, see the user guide's [prerequisites][] and https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-dart-sass [Docsy user guide]: https://docsy.dev/docs [hugo-extended]: https://www.npmjs.com/package/hugo-extended -[Docsy]: https://github.com/google/docsy +[Docsy]: https://github.com/docsy/docsy [maintainer notes]: CONTRIBUTING.md#maintainer-notes [example.docsy.dev]: https://example.docsy.dev [Hugo theme module]: https://gohugo.io/hugo-modules/