Skip to content

docs: add README, CHANGELOG, NOTICE, SECURITY, and LLM docs bundle (#17)#26

Merged
millerjp merged 3 commits into
mainfrom
docs/readme-changelog-notice-security-17
Apr 21, 2026
Merged

docs: add README, CHANGELOG, NOTICE, SECURITY, and LLM docs bundle (#17)#26
millerjp merged 3 commits into
mainfrom
docs/readme-changelog-notice-security-17

Conversation

@millerjp

@millerjp millerjp commented Apr 21, 2026

Copy link
Copy Markdown

Summary

Phase 5 Part 1 — user-facing documentation + AI-assistant bundle + markdownlint/llms-full CI guards + documentation tests adapted from axonops/mask.

Closes #17.

What's in this PR

File State
README.md rewrite — shop-front hero, Quick Start (compiles), full API table, thread safety, performance, when-to-use, AI assistants, security, attribution, licence
CHANGELOG.md new — Keep-a-Changelog format, v1.0.0 entry documents every fork change
NOTICE new — AxonOps + Robert Gooding / rgooding/go-syncmap attribution
SECURITY.md new — syncmap-specific threat model
llms.txt new — 1115-word AI-assistant summary
llms-full.txt new — 708-line concatenated corpus (generated)
scripts/gen-llms-full.sh new, executable
.markdownlint-cli2.yaml new — mask config adapted to syncmap globs
Makefile + llms-full and llms-full-check targets
.github/workflows/ci.yml + markdownlint guard job + llms-full-up-to-date guard job + 2 new entries in makefile-targets-guard expected list
documentation_test.go new — 9 AI-friendliness / governance tests adapted from mask

AI-friendliness tests (new)

  • TestLLMs_TxtExists_AndUnderTokenBudget — llms.txt exists and 200 < words ≤ 2250.
  • TestLLMs_FullTxtExists_AndIncludesSpecifiedSections — every required section header present.
  • TestLLMs_FullTxtIsUpToDate — regenerate via scripts/gen-llms-full.sh and byte-compare.
  • TestExamples_AllRequiredExamplesExist — all 15 required Example* functions parsed from example_test.go.
  • TestDocumentation_EveryExportedSymbolHasGodoc — parses the package and asserts every exported symbol has ≥20-char non-mechanical godoc (tuned to allow multi-line docs whose first line happens to open with a typical Xxx returns … pattern).
  • TestReadmeQuickStart_Compiles — extracts the Quick Start \``goblock, materialises a scratch module with areplaceback to the repo,go build`s and runs it, and asserts the documented output.
  • TestGovernance_NoticeFileExists / TestGovernance_SecurityPolicyExists / TestGovernance_ChangelogHasV1Entry — presence + content invariants.

Local validation

$ make check
(14/14 gates green, coverage 100%, govulncheck clean)

$ make llms-full-check
(idempotent — no diff)

$ ./node_modules/.bin/markdownlint-cli2 README.md SECURITY.md CHANGELOG.md
Summary: 0 error(s)

$ actionlint .github/workflows/ci.yml
clean

Upstream-licence reconciliation

Verified via gh api /repos/rgooding/go-syncmap/license: upstream is already Apache 2.0. README / NOTICE / CHANGELOG now consistently say "distributed under Apache 2.0; this fork continues under the same licence" — no "relicensing" wording.

Agent gates

  • docs-writer (post) — initially flagged the relicensing wording inconsistency (fixed) and a phantom future-date concern (the CHANGELOG date is today). Now clean.
  • go-quality — 14/14 PASS.
  • commit-message-reviewer — PASS (subject 72 chars exactly).

Deferrals

Test plan

  • All 16 CI jobs green — including the two newly enabled (markdownlint, llms-full.txt is up to date)
  • Coverage remains 100%
  • TestReadmeQuickStart_Compiles passes on the ubuntu and macOS matrix

millerjp added 3 commits April 21, 2026 06:31
@millerjp
docs: add README, CHANGELOG, NOTICE, SECURITY, and LLM docs bundle (#17)
a45f8b5 
Phase 5 user-facing documentation:

  * README.md — rewritten from the 1-line placeholder. Shop-front
    hero, TOC, Quick Start (compiles via TestReadmeQuickStart_Compiles),
    full API reference table, thread-safety notes, performance
    section linking bench.txt, when-to-use guidance, AI assistant
    section, security + attribution + licence.
  * CHANGELOG.md — Keep-a-Changelog format; v1.0.0 entry enumerates
    every fork change including the Items→Values breaking rename
    from #12, Swap+Clear from #13, and CompareAndSwap/Delete from
    #14. Upstream credited as Apache 2.0 already; no relicensing.
  * NOTICE — AxonOps Limited + Robert Gooding / rgooding/go-syncmap
    upstream attribution.
  * SECURITY.md — supported-versions table, syncmap-specific threat
    model (concurrency primitive), private-reporting contact
    oss@axonops.com.
  * llms.txt — concise AI-assistant summary (1115 words, under the
    2250 budget). Includes the attribution-guard rule so any
    assistant reading it knows not to sign commits with AI tokens.
  * llms-full.txt — generated concatenation of llms.txt, README,
    doc.go package comment, SECURITY, CHANGELOG, and go doc -all.
  * scripts/gen-llms-full.sh — adapted from mask; source list
    tailored to the files syncmap has today.
  * .markdownlint-cli2.yaml — mask config with syncmap-specific
    globs (no docs/rules.md / docs/extending.md).
  * Makefile — new llms-full and llms-full-check targets;
    makefile-targets-guard expected list extended.
  * .github/workflows/ci.yml — markdownlint and llms-full-up-to-date
    jobs enabled.
  * documentation_test.go — AI-friendliness and governance tests
    adapted from mask: llms.txt budget, llms-full.txt section
    headers, llms-full.txt byte-equality via regenerated script,
    required Example functions present, every exported symbol has
    real (non-mechanical, multi-line) godoc, README Quick Start
    compiles and produces the documented output, NOTICE /
    SECURITY / CHANGELOG governance presence checks.

Remaining Phase 5 content (CONTRIBUTING, CLA, CODE_OF_CONDUCT,
CONTRIBUTORS, cla.yml/contributors.yml workflows) is tracked by #18.

Coverage remains 100%.
@millerjp
docs: soften README attribution rule to pass attribution-guard (#17)
b483cc9 
The previous README phrasing enumerated the forbidden AI-tooling
tokens verbatim, which tripped the attribution-guard CI job (it scans
README.md; the token list belongs to policy-bearing files like
llms.txt and the eventual CONTRIBUTING.md which are on the guard's
exclusion list). Rewrite the paragraph to describe the policy and
link to llms.txt + the guard without listing the tokens directly.

Regenerate llms-full.txt to pick up the README change so
llms-full-up-to-date stays green.
@millerjp
ci: make attribution-guard filter pipeline strict-mode tolerant (#17)
249802b 
The guard's inner pipeline `grep -Ii... | grep -vi...` returns exit 1
when the filter strips every matched line (legitimate case — every
hit is a benign path reference). Under `set -euo pipefail` that
non-zero pipeline exit propagates through the command substitution
and aborts the script before the ::error:: print, so CI reports a
failure with no indication of which file actually triggered.

Wrap the filter in `{ … || true; }` so the pipeline always exits 0.
Behaviour is unchanged — `match` is still the filtered output; only
the pipeline exit code differs.
@millerjp millerjp merged commit 70af960 into main Apr 21, 2026
17 checks passed
@millerjp millerjp deleted the docs/readme-changelog-notice-security-17 branch April 21, 2026 04:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: add README, CHANGELOG, NOTICE, SECURITY, and LLM docs bundle

1 participant

@millerjp