Skip to content

docs: add CONTRIBUTING, CLA, CoC, CONTRIBUTORS and CLA workflows (#18)#27

Merged
millerjp merged 1 commit into
mainfrom
docs/contributing-cla-coc-contributors-18
Apr 21, 2026
Merged

docs: add CONTRIBUTING, CLA, CoC, CONTRIBUTORS and CLA workflows (#18)#27
millerjp merged 1 commit into
mainfrom
docs/contributing-cla-coc-contributors-18

Conversation

@millerjp

Copy link
Copy Markdown

Summary

Closes Phase 5 Part 2 — governance documentation + CLA Assistant automation + contributors regenerator. This is the last remaining issue in the v1.0.0 roadmap.

Closes #18.

What's in this PR

File State
CONTRIBUTING.md new — syncmap-specific, not a mask copy. Agent-gate stack split per-commit vs per-issue.
CLA.md new — mask template with syncmap repo refs; Apache Licence 2.0 grant unchanged.
CODE_OF_CONDUCT.md new — Contributor Covenant v2.1, oss@axonops.com enforcement contact.
CONTRIBUTORS.md new — script-generated; TestGovernance_ContributorsFileIsGenerated enforces byte-equality.
signatures/version1/cla.json new — empty signedContributors skeleton.
scripts/generate-contributors.sh new — idempotent jq-driven regenerator.
.github/workflows/cla.yml new — CLA Assistant (requires CLA_ASSISTANT_PAT secret).
.github/workflows/contributors.yml new — triggers on signature commits; runs generator; pushes back.
.github/workflows/ci.yml markdownlint globs extended to include new docs.
scripts/gen-llms-full.sh updated to include CONTRIBUTING.md.
llms-full.txt regenerated — 6308 words.
documentation_test.go +7 governance tests (Contributing / CLA / CoC / CLAWorkflow / ContributorsWorkflow / ContributorsFileIsGenerated / SignaturesFileIsValid).

Operational prerequisite

The cla.yml workflow requires a CLA_ASSISTANT_PAT repository secret with admin:repo scope to bypass branch protection when it commits signatures. Create it manually at Settings → Secrets and variables → Actions before the first external PR lands. Without the secret, the workflow will run but the signature-push step will fail.

Local validation

$ make check
(all gates green, coverage 100%)

$ go test -race -run 'TestGovernance_' -v ./...
all 10 governance tests PASS

$ ./scripts/generate-contributors.sh signatures/version1/cla.json /tmp/regen.md
$ diff CONTRIBUTORS.md /tmp/regen.md
(zero diff — script output matches committed file)

$ ./scripts/gen-llms-full.sh && make llms-full-check
(zero diff — idempotent)

$ npx markdownlint-cli2 --config .markdownlint-cli2.yaml CONTRIBUTING.md CLA.md CODE_OF_CONDUCT.md CONTRIBUTORS.md
Summary: 0 error(s)

$ actionlint .github/workflows/*.yml
clean

Agent gates

  • docs-writer (post) — initially flagged a CLA path typo (signatures/cla/cla.jsonsignatures/version1/cla.json), an agent-gate ordering issue in CONTRIBUTING (non-negotiable vs per-commit bucketing), and an American-spelling License in CONTRIBUTING's footer. All three fixed.
  • go-quality — 8/8 PASS.
  • commit-message-reviewer — PASS (subject 68 chars).

v1.0.0 readiness

Merging this PR closes the last v1.0.0 roadmap item. After merge, the repo is ready for release via workflow_dispatch of release.yml — the workflow runs the full gate, creates the tag from github-actions[bot], runs GoReleaser, and warms the Go module proxy.

Test plan

  • All CI jobs green — including the newly expanded Markdown lint globs and the 10 TestGovernance_* tests
  • llms-full.txt is up to date job passes against the regenerated file
  • No new documentation drift in documentation_test.go

Phase 5 Part 2 — governance documentation and CI automation:

  * CONTRIBUTING.md — branching, commits, test requirements,
    agent-gate stack (per-commit / per-issue split), performance
    baseline, release discipline, security reporting. British
    English throughout.
  * CLA.md — AxonOps contributor licence agreement, adapted from
    the axonops/mask template with project-name substitutions.
    Apache Licence 2.0 wording unchanged. Signatures path points at
    signatures/version1/cla.json.
  * CODE_OF_CONDUCT.md — Contributor Covenant v2.1 with the
    oss@axonops.com enforcement contact.
  * CONTRIBUTORS.md — generated from signatures/version1/cla.json
    via scripts/generate-contributors.sh; byte-equality enforced by
    TestGovernance_ContributorsFileIsGenerated.
  * signatures/version1/cla.json — empty signedContributors
    skeleton. CLA Assistant appends to this file on first signature.
  * scripts/generate-contributors.sh — idempotent jq-driven
    regenerator; mirrors mask's script with syncmap repo refs.
  * .github/workflows/cla.yml — CLA Assistant wiring. Requires the
    CLA_ASSISTANT_PAT repo secret for branch-protection bypass.
  * .github/workflows/contributors.yml — triggers on signature
    changes, regenerates CONTRIBUTORS.md, commits back to main via
    github-actions[bot].
  * .github/workflows/ci.yml — Markdown lint globs extended to
    include CONTRIBUTING / CLA / CoC / CONTRIBUTORS.
  * scripts/gen-llms-full.sh — source list now includes
    CONTRIBUTING.md; llms-full.txt regenerated.
  * documentation_test.go — seven new governance tests covering
    presence, byte-equality, CLA/CoC/contributor workflow wiring,
    and signatures-file schema.

Completes Phase 5 of the v1.0.0 roadmap. Coverage remains 100%.
@millerjp millerjp merged commit 75c7841 into main Apr 21, 2026
17 checks passed
@millerjp millerjp deleted the docs/contributing-cla-coc-contributors-18 branch April 21, 2026 05:15
@github-actions github-actions Bot locked and limited conversation to collaborators Apr 21, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add CONTRIBUTING, CLA, CODE_OF_CONDUCT, CONTRIBUTORS and enable CLA/contributors workflows

1 participant