Repository navigation
docs: add README, CHANGELOG, NOTICE, SECURITY, and LLM docs bundle #17
Copy link
Copy link
Closed
Labels
P0Blocks releaseBlocks releasedocumentationImprovements or additions to documentationImprovements or additions to documentation
Description
docs: add README, CHANGELOG, NOTICE, SECURITY, and LLM docs bundle
Summary
Land the user-facing documentation bundle modelled on axonops/mask: a full README.md, CHANGELOG.md, NOTICE (crediting the original rgooding/go-syncmap author), SECURITY.md, llms.txt, and llms-full.txt (with the scripts/gen-llms-full.sh script that regenerates the latter). Re-enables the markdownlint and llms-full-up-to-date CI guard jobs that were deferred in #8.
Requirements
README.md— rewrite from the current 1-line placeholder. Structure mirrors mask's README. Sections:- Logo / tagline (use
gopher.pngat repo root if it passes markdownlint image-alt requirements) - Project description
- Installation:
go get github.com/axonops/syncmap - Quick Start (copy-paste-runnable complete program)
- API Reference (every public symbol — signature + one-sentence description + link to godoc)
- Thread Safety (inherits from
sync.Map) - Performance (link to
bench.txtand summarise overhead vs rawsync.Map) - When to Use (
SyncMapvssync.Mapvsmap+sync.RWMutex) - Contributing (link to
CONTRIBUTING.md) - Attribution (fork of
github.com/rgooding/go-syncmapby Robert Gooding) - Licence
- CI badge(s) matching mask's README
- Logo / tagline (use
CHANGELOG.md— Keep-a-Changelog structure. Seed with the v1.0.0 entry listing every change from the fork: module rename, Go 1.26, method renames/additions, CI/release setup, docs, tests. Future versions documented as they cut.NOTICE— Apache 2.0 attribution block that names AxonOps Limited AND credits Robert Gooding /github.com/rgooding/go-syncmapas the original source. Wording modelled on mask's NOTICE.SECURITY.md— mirror mask's SECURITY.md exactly, substitutingmask→syncmapin the reporting URL / email as appropriate.llms.txt— mirror mask's llms.txt structure (common mistakes AI assistants make; project overview for LLM context).llms-full.txt— generated concatenation of the policy-bearing docs; produced byscripts/gen-llms-full.sh.scripts/gen-llms-full.sh— mirror mask's script verbatim (adjust source file list to syncmap's docs).- Makefile — re-add the
llms-fullandllms-full-checktargets (removed in chore: align CI, release, and tooling to axonops/mask pattern #8). Updatemakefile-targets-guardexpected list accordingly. - CI:
- Re-enable
markdownlintjob inci.yml(usesDavidAnson/markdownlint-cli2-action@v21.0.0per mask pin) and listREADME.md,CHANGELOG.md,CONTRIBUTING.md,SECURITY.md,NOTICE,CLA.md,CODE_OF_CONDUCT.md,CONTRIBUTORS.md(the ones that exist by merge time) in itsglobs:input. - Re-enable
llms-full-up-to-datejob inci.yml.
- Re-enable
- All new files carry appropriate licence / attribution. No AI-attribution tokens outside the llms files (where tool names are product references, already excluded by
attribution-guard).
Acceptance Criteria
README.md≥150 lines; contains every section listed in Req 1.CHANGELOG.mdhas a populated## [1.0.0]section.NOTICEnames both AxonOps Limited and Robert Gooding (rgooding/go-syncmap).SECURITY.mdexists and documents private disclosure.llms.txtandllms-full.txtexist at repo root.scripts/gen-llms-full.shis executable and idempotent.make llms-fullregeneratesllms-full.txtwithout diff.make llms-full-checkexits 0 on an unchanged tree.markdownlintCI job passes on this PR.llms-full-up-to-dateCI job passes on this PR.makefile-targets-guardpasses withllms-fullandllms-full-checkre-added.make checkgreen; CI green end-to-end.grep -i 'rgooding/go-syncmap' NOTICE CHANGELOG.md README.mdreturns at least one hit in each.
Testing Requirements
go test -run 'Example' ./...— if examples exist, they continue to pass (this issue adds prose, not test code).- CI — all green including the two re-enabled guards.
markdownlint-cli2locally against the doc file list — zero warnings.make llms-full-checkon unchanged tree — exit 0.
Documentation Requirements
- This IS the documentation issue.
Dependencies
- Blocked by: docs: add doc.go and rewrite godoc on every exported symbol #11 (godoc — README's API Reference quotes it), chore: align CI, release, and tooling to axonops/mask pattern #8 rename (if it merged — else README carries the old name), chore: align CI, release, and tooling to axonops/mask pattern (#8) #9/test: rewrite unit tests to external package with testify/goleak; coverage ≥95% #10 (README's API Reference table), feat!: rename Items to Values #12 (
bench.txtmust exist so README can link to it). - Blocks: v1.0.0 — no release without README.
Labels
documentationP0
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
P0Blocks releaseBlocks releasedocumentationImprovements or additions to documentationImprovements or additions to documentation
Activity
millerjp commentedon Apr 20, 2026
Bookkeeping from #12 (merged via PR #21): the initial CHANGELOG.md added in this issue must include the
Items→Valuesrename under the v1.0.0### Breakingsection. Issue #12 explicitly deferred the CHANGELOG entry here.millerjp commentedon Apr 20, 2026
Bookkeeping from #14 (merged via PR #22): when CHANGELOG.md lands here, it must include an
### Addedentry under v1.0.0 naming the new package-levelCompareAndSwapandCompareAndDeletefunctions.millerjp commentedon Apr 20, 2026
Bookkeeping from #13 (merged via PR #23): CHANGELOG must include
### Addedentries under v1.0.0 naming the newSwapandClearmethods.docs: soften README attribution rule to pass attribution-guard (#17)
ci: make attribution-guard filter pipeline strict-mode tolerant (#17)
docs: add README, CHANGELOG, NOTICE, SECURITY, and LLM docs bundle (#17)