Add docs foundation: README, CLAUDE.md, swagger specs

ldraney commented

2026-06-13 15:20:07 +00:00

Owner

Summary

README as table of contents with mermaid diagrams (architecture, pipeline, testing strategy), CLAUDE.md symlinked to it
All 10 official GoDaddy swagger specs added to docs/ with api-groups.md overview (121 endpoints, 97 paths)
Reference docs for DNS endpoints (Go client + HCL mapping) and sso-key auth setup

Changes

README.md — full rewrite as TOC, includes provider schema examples, project structure, testing strategy
CLAUDE.md — symlink to README.md
docs/api-groups.md — new, endpoint/path counts per swagger spec
docs/dns-endpoints.md — new, DNS CRUD reference with HCL resource mapping
docs/auth.md — new, credential setup and Go client auth flow
docs/swagger_*.json — all 10 official swagger specs from developer.godaddy.com

Test Plan

All 10 swagger JSON files parse correctly
readlink CLAUDE.md returns README.md
All doc links resolve
Mermaid diagrams render in Forgejo

Review Checklist

Passed automated review-fix loop
No secrets committed
No unnecessary file changes
Commit messages are descriptive
Feature flag needed? No — docs only

Closes #1
project-godaddy-tofu — project page
project-godaddy-sdk — swagger specs sourced from this project

## Summary - README as table of contents with mermaid diagrams (architecture, pipeline, testing strategy), CLAUDE.md symlinked to it - All 10 official GoDaddy swagger specs added to docs/ with api-groups.md overview (121 endpoints, 97 paths) - Reference docs for DNS endpoints (Go client + HCL mapping) and sso-key auth setup ## Changes - `README.md` — full rewrite as TOC, includes provider schema examples, project structure, testing strategy - `CLAUDE.md` — symlink to README.md - `docs/api-groups.md` — new, endpoint/path counts per swagger spec - `docs/dns-endpoints.md` — new, DNS CRUD reference with HCL resource mapping - `docs/auth.md` — new, credential setup and Go client auth flow - `docs/swagger_*.json` — all 10 official swagger specs from developer.godaddy.com ## Test Plan - [ ] All 10 swagger JSON files parse correctly - [ ] `readlink CLAUDE.md` returns `README.md` - [ ] All doc links resolve - [ ] Mermaid diagrams render in Forgejo ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive - [ ] Feature flag needed? No — docs only ## Related Notes - Closes #1 - `project-godaddy-tofu` — project page - `project-godaddy-sdk` — swagger specs sourced from this project

ldraney added 1 commit

2026-06-13 15:20:07 +00:00

Add docs foundation: README TOC, CLAUDE.md symlink, swagger specs 75d1c2bf88

README serves as table of contents with mermaid diagrams for architecture,
pipeline, and testing strategy. CLAUDE.md symlinks to README for agent
context. docs/ contains all 10 GoDaddy swagger specs plus reference docs
for API groups, DNS endpoints, and auth setup — all framed for the Go
provider and Terraform Plugin Framework.

Closes #1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ldraney commented

2026-06-13 15:23:24 +00:00

Author

Owner

PR #2 Review

DOMAIN REVIEW

Tech stack: Go / OpenTofu provider -- this PR is docs-only (Markdown + Mermaid + swagger JSON), so domain checks focus on documentation quality and accuracy.

README.md -- Well-structured table of contents. Three mermaid diagrams (architecture, pipeline, testing strategy) clearly communicate the provider's design. Provider schema examples use HCL with env-var-backed credentials (no hardcoded secrets). Project structure tree matches the planned codebase layout. Development commands reference the correct env vars (GODADDY_API_KEY, GODADDY_API_SECRET, TF_ACC).

docs/api-groups.md -- Clean endpoint inventory table with counts per swagger spec. Relative links to swagger files (swagger_domains.json) are correct for same-directory references. The summary line ("121 endpoints across 97 paths in 10 swagger specs") provides useful context. The closing paragraph correctly notes that DNS endpoints live inside the domains spec.

docs/dns-endpoints.md -- Solid P0 endpoint reference. The mermaid diagram and endpoint table both clearly map HTTP methods to Go client methods and provider resource operations. Good call-out that bulk replacement endpoints (the bottom 3) are exposed in the client but intentionally NOT used by the provider -- this documents the safety decision to avoid the destructive bulk-replace pattern.

docs/auth.md -- Clean sequence diagram showing the auth flow. Credential setup instructions use chmod 600 on the secrets file. OTE vs production base URL distinction is documented. Go client usage shows both production and OTE patterns.

CLAUDE.md -- Symlink (mode 120000) to README.md. Appropriate approach -- agents get the README as context without maintaining a separate file.

BLOCKERS

None.

NITS

CLAUDE.md missing trailing newline -- The symlink file has \ No newline at end of file. Not functionally broken (symlinks are resolved by the filesystem, not parsed as text), but most tools expect a trailing newline. Non-blocking.
PR body Summary section -- Template says "1-3 bullet points"; this PR has 6. Fine for a multi-file docs PR, but worth noting for future PRs.
Rate limit section in dns-endpoints.md is sparse -- "60 requests per minute per API key" is stated without a source reference. Consider linking to the GoDaddy API docs or the relevant swagger spec where this is documented. Non-blocking.

SOP COMPLIANCE

Branch named after issue (1-docs-foundation references issue #1)
PR body follows template-pr-body (Summary, Changes, Test Plan, Review Checklist, Related Notes all present)
Closes #1 present in Related Notes
Related Notes references project slugs (project-godaddy-tofu, project-godaddy-sdk)
No secrets committed (credential examples use placeholder values)
No unnecessary file changes (all 15 files are docs or swagger specs, scoped to issue #1)
Commit messages -- not individually visible in the diff, but PR title is descriptive
Feature flag consideration addressed in Review Checklist ("No -- docs only")
OpenTofu platform additions -- N/A (no .tf files in this PR, docs only)

PROCESS OBSERVATIONS

This is a strong docs foundation PR. The swagger specs provide the raw API reference, and the hand-written docs distill them into actionable guidance for provider development.
The README's mermaid diagrams will serve as living architecture docs as the provider is built out.
DORA: No deployment risk (docs only). Sets up the knowledge base needed for subsequent implementation PRs.

VERDICT: APPROVED

## PR #2 Review ### DOMAIN REVIEW **Tech stack:** Go / OpenTofu provider -- this PR is docs-only (Markdown + Mermaid + swagger JSON), so domain checks focus on documentation quality and accuracy. **README.md** -- Well-structured table of contents. Three mermaid diagrams (architecture, pipeline, testing strategy) clearly communicate the provider's design. Provider schema examples use HCL with env-var-backed credentials (no hardcoded secrets). Project structure tree matches the planned codebase layout. Development commands reference the correct env vars (`GODADDY_API_KEY`, `GODADDY_API_SECRET`, `TF_ACC`). **docs/api-groups.md** -- Clean endpoint inventory table with counts per swagger spec. Relative links to swagger files (`swagger_domains.json`) are correct for same-directory references. The summary line ("121 endpoints across 97 paths in 10 swagger specs") provides useful context. The closing paragraph correctly notes that DNS endpoints live inside the domains spec. **docs/dns-endpoints.md** -- Solid P0 endpoint reference. The mermaid diagram and endpoint table both clearly map HTTP methods to Go client methods and provider resource operations. Good call-out that bulk replacement endpoints (the bottom 3) are exposed in the client but intentionally NOT used by the provider -- this documents the safety decision to avoid the destructive bulk-replace pattern. **docs/auth.md** -- Clean sequence diagram showing the auth flow. Credential setup instructions use `chmod 600` on the secrets file. OTE vs production base URL distinction is documented. Go client usage shows both production and OTE patterns. **CLAUDE.md** -- Symlink (mode 120000) to README.md. Appropriate approach -- agents get the README as context without maintaining a separate file. ### BLOCKERS None. ### NITS 1. **CLAUDE.md missing trailing newline** -- The symlink file has `\ No newline at end of file`. Not functionally broken (symlinks are resolved by the filesystem, not parsed as text), but most tools expect a trailing newline. Non-blocking. 2. **PR body Summary section** -- Template says "1-3 bullet points"; this PR has 6. Fine for a multi-file docs PR, but worth noting for future PRs. 3. **Rate limit section in dns-endpoints.md is sparse** -- "60 requests per minute per API key" is stated without a source reference. Consider linking to the GoDaddy API docs or the relevant swagger spec where this is documented. Non-blocking. ### SOP COMPLIANCE - [x] Branch named after issue (`1-docs-foundation` references issue #1) - [x] PR body follows `template-pr-body` (Summary, Changes, Test Plan, Review Checklist, Related Notes all present) - [x] `Closes #1` present in Related Notes - [x] Related Notes references project slugs (`project-godaddy-tofu`, `project-godaddy-sdk`) - [x] No secrets committed (credential examples use placeholder values) - [x] No unnecessary file changes (all 15 files are docs or swagger specs, scoped to issue #1) - [x] Commit messages -- not individually visible in the diff, but PR title is descriptive - [x] Feature flag consideration addressed in Review Checklist ("No -- docs only") - [x] OpenTofu platform additions -- N/A (no `.tf` files in this PR, docs only) ### PROCESS OBSERVATIONS - This is a strong docs foundation PR. The swagger specs provide the raw API reference, and the hand-written docs distill them into actionable guidance for provider development. - The README's mermaid diagrams will serve as living architecture docs as the provider is built out. - DORA: No deployment risk (docs only). Sets up the knowledge base needed for subsequent implementation PRs. ### VERDICT: APPROVED

ldraney added 1 commit

2026-06-13 15:30:10 +00:00

Fix rate limit claim: cite swagger ErrorLimit instead of unverified number 33292700f3

The 60 req/min figure had no source. The swagger spec documents a 429
response with retryAfterSec but doesn't publish the exact threshold.
Updated to reference the actual spec and recommend backoff behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>