Skip to content

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

Closed

Description

@millerjp

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

  1. README.md — rewrite from the current 1-line placeholder. Structure mirrors mask's README. Sections:
    • Logo / tagline (use gopher.png at 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.txt and summarise overhead vs raw sync.Map)
    • When to Use (SyncMap vs sync.Map vs map+sync.RWMutex)
    • Contributing (link to CONTRIBUTING.md)
    • Attribution (fork of github.com/rgooding/go-syncmap by Robert Gooding)
    • Licence
    • CI badge(s) matching mask's README
  2. 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.
  3. NOTICE — Apache 2.0 attribution block that names AxonOps Limited AND credits Robert Gooding / github.com/rgooding/go-syncmap as the original source. Wording modelled on mask's NOTICE.
  4. SECURITY.md — mirror mask's SECURITY.md exactly, substituting mask → syncmap in the reporting URL / email as appropriate.
  5. llms.txt — mirror mask's llms.txt structure (common mistakes AI assistants make; project overview for LLM context).
  6. llms-full.txt — generated concatenation of the policy-bearing docs; produced by scripts/gen-llms-full.sh.
  7. scripts/gen-llms-full.sh — mirror mask's script verbatim (adjust source file list to syncmap's docs).
  8. Makefile — re-add the llms-full and llms-full-check targets (removed in chore: align CI, release, and tooling to axonops/mask pattern #8). Update makefile-targets-guard expected list accordingly.
  9. CI:
    • Re-enable markdownlint job in ci.yml (uses DavidAnson/markdownlint-cli2-action@v21.0.0 per mask pin) and list README.md, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, NOTICE, CLA.md, CODE_OF_CONDUCT.md, CONTRIBUTORS.md (the ones that exist by merge time) in its globs: input.
    • Re-enable llms-full-up-to-date job in ci.yml.
  10. 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

  1. README.md ≥150 lines; contains every section listed in Req 1.
  2. CHANGELOG.md has a populated ## [1.0.0] section.
  3. NOTICE names both AxonOps Limited and Robert Gooding (rgooding/go-syncmap).
  4. SECURITY.md exists and documents private disclosure.
  5. llms.txt and llms-full.txt exist at repo root.
  6. scripts/gen-llms-full.sh is executable and idempotent.
  7. make llms-full regenerates llms-full.txt without diff.
  8. make llms-full-check exits 0 on an unchanged tree.
  9. markdownlint CI job passes on this PR.
  10. llms-full-up-to-date CI job passes on this PR.
  11. makefile-targets-guard passes with llms-full and llms-full-check re-added.
  12. make check green; CI green end-to-end.
  13. grep -i 'rgooding/go-syncmap' NOTICE CHANGELOG.md README.md returns 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-cli2 locally against the doc file list — zero warnings.
  • make llms-full-check on unchanged tree — exit 0.

Documentation Requirements

  • This IS the documentation issue.

Dependencies

Labels

  • documentation
  • P0

Activity

  1. added
    documentationImprovements or additions to documentation
    P0Blocks release
    on Apr 20, 2026
  2. millerjp commented on Apr 20, 2026

    @millerjp
    Author

    Bookkeeping from #12 (merged via PR #21): the initial CHANGELOG.md added in this issue must include the Items → Values rename under the v1.0.0 ### Breaking section. Issue #12 explicitly deferred the CHANGELOG entry here.

  3. millerjp commented on Apr 20, 2026

    @millerjp
    Author

    Bookkeeping from #14 (merged via PR #22): when CHANGELOG.md lands here, it must include an ### Added entry under v1.0.0 naming the new package-level CompareAndSwap and CompareAndDelete functions.

  4. millerjp commented on Apr 20, 2026

    @millerjp
    Author

    Bookkeeping from #13 (merged via PR #23): CHANGELOG must include ### Added entries under v1.0.0 naming the new Swap and Clear methods.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P0Blocks releasedocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions