Skip to content

docs: add contributor, security, and changelog docs - #23

Merged
patramsey merged 1 commit into
mainfrom
docs/community-health
Aug 2, 2026
Merged

docs: add contributor, security, and changelog docs#23
patramsey merged 1 commit into
mainfrom
docs/community-health

Conversation

@patramsey

@patramsey patramsey commented Aug 2, 2026

Copy link
Copy Markdown
Owner

Docs and config only. No production code changes.

The repo was public with a README and a LICENSE and nothing else — no statement of how to contribute, no conduct policy, no private channel for reporting a vulnerability, no release history outside the auto-generated tag notes. GitHub's community-standards checklist flagged all four.

These are tailored rather than boilerplate, because the generic version is wrong in the places that matter for a tool holding registrar credentials.

CONTRIBUTING.md

Documents the two invariants that are easy to break by accident:

  • POST is only retried when X-Idempotency-Key is set. Relaxing that can double-register a domain.
  • dns update / domain update are read-modify-write, because the API does full PUT replacement. A partial body silently drops fields.

Plus the things that aren't guessable from the tree: why -count=1 is required (internal/api/gen shells out to scripts/spec_to_30.py and reads namecom.api.yaml; Go's test cache tracks neither, so a cached pass hides a broken preprocessor), that zz_generated.go and namecom.api.yaml are not hand-edited, and that re-vendoring the spec means updating SPEC_SHA in the same commit.

SECURITY.md

Scopes the categories that actually apply here rather than generic ones: token leakage via --debug/--debug-file or config file modes, the token_cmd shell exec, a command whose real request diverges from its --dry-run preview, and sandbox/production confusion. Says not to paste a live token into a report.

Private vulnerability reporting has been enabled on the repo, so the link in this file resolves.

Issue / PR templates

The bug template asks for --dry-run output on mutating commands — the single most useful artifact for diagnosing one — and warns that --debug output carries request/response bodies even though the token is redacted. The PR template has a matching checklist item for TestDryRunMatchesRealRequest_*.

CHANGELOG.md

Starts at 0.2.0. Reconstructing entries for the fourteen earlier tags would have meant inventing detail the commit history doesn't support (Feat/fix bugs (#9)), so it points at the releases page for those instead.

.gitignore

Grows .superpowers/ and docs/plans/ alongside the existing .claude/ entry. Agent working artifacts are a record of how the work was produced, not something a contributor needs, and they land in the tree next to real source — which makes them easy to stage by accident.

Note on CLAUDE.md

It stays gitignored here, so CONTRIBUTING.md inlines the architecture context a contributor needs instead of linking to a file that doesn't exist on GitHub.

Test plan

  • go build ./... && go vet ./... clean
  • Every relative link in the new files and the README resolves to a tracked (or newly added) path — verified by script, 15/15
  • No production code touched, so no behavior to test

The repo was public with a README and a LICENSE and nothing else — no
statement of how to contribute, no conduct policy, no way to report a
vulnerability privately, no release history outside the auto-generated
tag notes. GitHub's community-standards checklist flagged all four.

Everything here is tailored rather than boilerplate, because the generic
version would be wrong in the places that matter for this tool:

- CONTRIBUTING.md documents the two invariants that are easy to break by
  accident. POST is only retried when X-Idempotency-Key is set, and
  relaxing that can double-register a domain. dns/domain update are
  read-modify-write because the API does full PUT replacement, so a
  partial body silently drops fields. It also spells out why `-count=1`
  is required (internal/api/gen shells out to spec_to_30.py and reads
  namecom.api.yaml; Go's cache tracks neither) and that zz_generated.go
  and namecom.api.yaml are not hand-edited.

- SECURITY.md scopes the categories that actually apply to a tool holding
  registrar credentials: token leakage through --debug/--debug-file or a
  config file, the token_cmd shell exec, a command whose real request
  diverges from its --dry-run preview, and sandbox/production confusion.
  It also says not to paste a live token into a report.

- Issue templates ask for --dry-run output on mutating commands, which is
  the single most useful artifact for diagnosing one, and warn that
  --debug output contains request/response bodies even though the token
  is redacted.

- CHANGELOG.md starts at 0.2.0. Reconstructing entries for the fourteen
  earlier tags would have meant inventing detail the commit history does
  not support, so it points at the releases page for those instead.

.gitignore grows .superpowers/ and docs/plans/ alongside the existing
.claude/ entry. Agent working artifacts are a record of how the work was
produced, not something a contributor needs, and they land in the tree
next to real source, which makes them easy to stage by accident.

CLAUDE.md stays gitignored here, so CONTRIBUTING.md inlines the
architecture context a contributor needs rather than linking to a file
that does not exist on GitHub.
@patramsey
patramsey force-pushed the docs/community-health branch from 0d5f266 to f6c4d84 Compare August 2, 2026 18:48
@patramsey
patramsey merged commit fcde584 into main Aug 2, 2026
3 checks passed
@patramsey
patramsey deleted the docs/community-health branch August 2, 2026 18:50
patramsey added a commit that referenced this pull request Aug 2, 2026
#24 merged without a changelog entry because CHANGELOG.md itself only
arrived in #23, which landed at the same time. This backfills it.

Also corrects "No user-facing behavior changes yet", which #24 made
false: `namecom open` now rejects an argument that is not a plausible
domain name rather than passing it through. Someone who was relying on
`open` to accept an arbitrary string will notice, so it belongs under
Changed as well as Security.

The race fix in #25 is deliberately not listed. It is test-only
bookkeeping with no user-visible effect, and Keep a Changelog is for
notable changes rather than a commit log.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant