Phase 04: Contributor Experience

[tazarov]

Summary

Phase 04: Contributor Experience
Goal: Any developer can understand, build, test, and contribute without reading source code
Status: Implementation complete — verification is docs/config only (no runtime surface to test beyond CI already validating the workflow files)

Ships the contributor-facing surface for the v0.1.0 OSS launch: a task-first CONTRIBUTING.md, a real SECURITY.md disclosure policy, a minimal three-badge README trust row, and a Dependabot config that will open weekly grouped update PRs once this lands.

Changes

Plan 04-01: Contributor docs + README trust row

• CONTRIBUTING.md (new) — opens with make help as the discovery step, documents the exact local commands (build, test, lint, security-scan)
• SECURITY.md (new) — coordinated disclosure policy, GitHub private vulnerability reporting with security@amikos.tech email fallback, no invented bug bounty
• README.md (modified) — locked to three badges: CI, Go Reference, MIT; single discovery sentence linking to the new docs

Commits: 7f5f258, f558bdd, e1d1ebb

Plan 04-02: Dependabot configuration

• .github/dependabot.yml (new) — single gomod root entry, weekly schedule (Mon 07:00 UTC), minor+patch grouped via gomod-minor-and-patch, major updates kept separate

Commit: d4e8d4a

Requirements Addressed

ID	Description
CONTR-01	CONTRIBUTING.md documents exact commands for build/test/lint/security-scan
CONTR-02	SECURITY.md documents vulnerability disclosure policy and contact
CONTR-03	README displays CI, Go Reference, and MIT badges linking to live targets
CONTR-04	Dependabot is configured (first automated PR observable once merged to main)

Verification

• Plan 04-01 complete — all artifacts present and referenced (see 04-01-SUMMARY.md)
• Plan 04-02 config shipped — YAML validated
• CONTR-04 final acceptance: requires observing first real Dependabot PR against main after this merges through the milestone branch (human checkpoint — flagged in 04-02-PLAN.md user_setup)
• No VERIFICATION.md produced — this phase is documentation + static config only; runtime verification is handled by the CI workflow from Phase 03 which already lints these files

Key Decisions

• CONTRIBUTING.md stays thin and points at the existing Makefile — no duplication of command semantics
• SECURITY.md uses conditional language for GitHub private reporting (in case it's disabled) with email as the stable fallback
• README trust row is deliberately minimal (3 badges) to avoid badge sprawl
• Dependabot config is root-only for now — sub-module support can follow when the repo grows one

Test plan

• Visual QA of README badges render correctly on GitHub
• CI passes on this branch (lint should flag any YAML issues in dependabot.yml)
• After merge to main via milestone branch: confirm first Dependabot PR appears within ~24h to close out CONTR-04

[tazarov]

@claude PTAL

[claude]

Claude finished @tazarov's task in 1m 27s —— View job

---

Review: Phase 04 Contributor Experience

• Gather context
• Read changed files
• Review .github/dependabot.yml
• Review CONTRIBUTING.md
• Review SECURITY.md
• Review README.md changes

---

Overall this is a clean, well-scoped PR. All four stated requirements (CONTR-01 through CONTR-04) are addressed and the files are consistent with each other. A few minor observations below — none are blockers.

.github/dependabot.yml

The config is correct. One thing to be aware of: the labels dependencies and go (lines 11–13) must already exist in the repo's label set or Dependabot will silently skip applying them. Worth creating those labels in GitHub before merging (or removing the labels block and adding them later). Not a CI failure — just means the first few PRs will be unlabelled until they exist.

The grouping strategy is correct: minor+patch consolidated into one weekly PR, each major kept separate. open-pull-requests-limit: 5 is reasonable.

CONTRIBUTING.md

Good: task-first, thin, and points at Makefile rather than duplicating it. The note that make test auto-installs gotestsum (line 7) is accurate.

Minor: golangci-lint and govulncheck are listed as prerequisites but no install command is provided. gotestsum gets special mention because the Makefile installs it automatically — the same parenthetical could note the quick-start for the other two:

golangci-lint:  https://golangci-lint.run/welcome/install/
govulncheck:    go install golang.org/x/vuln/cmd/govulncheck@latest

Not a blocker; a first-time contributor can find these, but it reduces friction if it's there. Fix this →

SECURITY.md

Looks good. Conditional language for the GitHub private-reporting channel is the right call. The 5-business-day acknowledgment SLA is realistic for a small OSS project. The "Supported Versions" section is appropriately vague for a pre-release library.

README.md

Badge row is correct. pkg.go.dev URL matches the module path (github.com/amikos-tech/ami-gin). MIT badge links to the local LICENSE file rather than a hardcoded SPDX URL — works fine since the file exists. The discovery sentence (linking to CONTRIBUTING.md and SECURITY.md) is clear and non-duplicative.

---

Summary: LGTM. The two items above (GitHub labels + optional install hints) are both nice-to-haves, not blockers. The repo is in good shape for the OSS v0.1.0 launch.