[PR #60] [MERGED] docs: add AGENTS.md covering codegen drift and public-repo hygiene #63

New issue

Closed

opened 2026-10-31 22:04:14 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 22:04:14 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-typescript-sdk/pull/60
Author: @christian-byrne
Created: 8/19/2026
Status: ✅ Merged
Merged: 8/23/2026
Merged by: @christian-byrne

Base: main ← Head: docs/agents-md

📝 Commits (2)

f2cb14f docs: add AGENTS.md covering codegen drift and public-repo hygiene
ca84f06 docs: satisfy oxfmt markdown formatting and note the docs format gate

📊 Changes

1 file changed (+150 additions, -0 deletions)

View changed files

➕ AGENTS.md (+150 -0)

📄 Description

Adds the contributor-facing scaffolding this repo was missing. Docs and config only — no source or workflow changes.

Closes #54
Closes #55
Closes #56
Closes #57

What's here

CONTRIBUTING.md (#54) — written for someone who has never seen the repo. Prereqs (Node >= 22, pnpm via Corepack), setup, and a table of the six checks CI runs with the exact commands, in CI's order. The section that matters most is Generated code (do not hand-edit): src/low/generated/{types.gen.ts,zod.gen.ts,index.ts} is produced from spec/openapi.yaml by pnpm generate, scripts/check-spec-drift.mjs is a required CI step that regenerates and diffs, and the fix for a drift failure is always pnpm generate && git add src/low/generated. It also covers why generated files must not be reformatted (the drift check compares bytes), why spec/openapi.yaml itself is not hand-editable (one-way sync, internal ops stripped), and the distinction between the hand-written src/low/index.ts and the generated src/low/generated/index.ts. Plus the public-repo-hygiene job — the three categories it flags and that extending the allowlist is the intended fix for a false positive — the build-check publish dry run, test conventions, Conventional Commits, CLA, CODEOWNERS review, and the tag-driven release flow (do not bump version in a PR).

.github/ISSUE_TEMPLATE/ (#55) — bug report and feature request, adapted from Comfy-Org/comfy-cli's templates rather than invented, so the shape is familiar across the org. Both add an Environment block asking for SDK version, Node version, and which surface (Cloud / serverless / self-hosted); the bug template asks for a minimal repro as a code block, and the feature template asks whether the request actually needs a contract change.

.github/dependabot.yml (#56) — npm and github-actions, weekly on Monday. Minor/patch bumps are grouped per ecosystem so a small repo with a small review pool gets one PR a week instead of one per dependency; majors stay individual, since those are the ones that need a real read. Commit prefixes match the repo's Conventional Commits (chore / ci).

CHANGELOG.md (#57) — keep-a-changelog. Seeded from the actual published release notes for v0.1.0 through v0.1.7, not fabricated: the two breaking changes (COMFY_BASE_URL in 0.1.6, the cloud.comfy.org move in 0.1.4) keep their upgrade snippets, and 0.1.7's assets.delete() keeps its proxy-version caveat. A header note says the historical entries were reconstructed and that the releases remain authoritative for those versions. Unreleased is empty with a comment explaining what belongs there.

Also adds a three-line pointer from the README's Development section to both new files.

Notes for review

One convention encoded from practice rather than from an existing doc: CONTRIBUTING says not to add AI-assistant attribution trailers to commit messages. Drop that line if you'd rather not state it.
CONTRIBUTING deliberately contains no literal ticket-shaped example ID — the public-repo-hygiene scanner reads this file too. node scripts/check-public-repo-hygiene.mjs passes on the branch.
No dependencies were installed to produce this, so the pnpm-based checks were not run locally; nothing here is TypeScript, and .github/dependabot.yml and both templates' front matter were parsed to confirm they are valid YAML.
AGENTS.md is intentionally absent — it's being added separately.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/comfy-typescript-sdk/pull/60 **Author:** [@christian-byrne](https://github.com/christian-byrne) **Created:** 8/19/2026 **Status:** ✅ Merged **Merged:** 8/23/2026 **Merged by:** [@christian-byrne](https://github.com/christian-byrne) **Base:** `main` ← **Head:** `docs/agents-md` --- ### 📝 Commits (2) - [`f2cb14f`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/f2cb14f2ce4b233ee48bead6e7b23987ff8ebc3a) docs: add AGENTS.md covering codegen drift and public-repo hygiene - [`ca84f06`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/ca84f0620c7eaf29aa3af7b2dc98f2224226108e) docs: satisfy oxfmt markdown formatting and note the docs format gate ### 📊 Changes **1 file changed** (+150 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `AGENTS.md` (+150 -0) </details> ### 📄 Description Adds the contributor-facing scaffolding this repo was missing. Docs and config only — no source or workflow changes. Closes #54 Closes #55 Closes #56 Closes #57 ## What's here **`CONTRIBUTING.md`** (#54) — written for someone who has never seen the repo. Prereqs (Node >= 22, pnpm via Corepack), setup, and a table of the six checks CI runs with the exact commands, in CI's order. The section that matters most is **Generated code (do not hand-edit)**: `src/low/generated/{types.gen.ts,zod.gen.ts,index.ts}` is produced from `spec/openapi.yaml` by `pnpm generate`, `scripts/check-spec-drift.mjs` is a required CI step that regenerates and diffs, and the fix for a drift failure is always `pnpm generate && git add src/low/generated`. It also covers why generated files must not be reformatted (the drift check compares bytes), why `spec/openapi.yaml` itself is not hand-editable (one-way sync, internal ops stripped), and the distinction between the hand-written `src/low/index.ts` and the generated `src/low/generated/index.ts`. Plus the `public-repo-hygiene` job — the three categories it flags and that extending the allowlist is the intended fix for a false positive — the `build-check` publish dry run, test conventions, Conventional Commits, CLA, CODEOWNERS review, and the tag-driven release flow (do not bump `version` in a PR). **`.github/ISSUE_TEMPLATE/`** (#55) — bug report and feature request, adapted from `Comfy-Org/comfy-cli`'s templates rather than invented, so the shape is familiar across the org. Both add an Environment block asking for SDK version, Node version, and which surface (Cloud / serverless / self-hosted); the bug template asks for a minimal repro as a code block, and the feature template asks whether the request actually needs a contract change. **`.github/dependabot.yml`** (#56) — `npm` and `github-actions`, weekly on Monday. Minor/patch bumps are grouped per ecosystem so a small repo with a small review pool gets one PR a week instead of one per dependency; majors stay individual, since those are the ones that need a real read. Commit prefixes match the repo's Conventional Commits (`chore` / `ci`). **`CHANGELOG.md`** (#57) — keep-a-changelog. Seeded from the actual published release notes for v0.1.0 through v0.1.7, not fabricated: the two breaking changes (`COMFY_BASE_URL` in 0.1.6, the `cloud.comfy.org` move in 0.1.4) keep their upgrade snippets, and 0.1.7's `assets.delete()` keeps its proxy-version caveat. A header note says the historical entries were reconstructed and that the releases remain authoritative for those versions. `Unreleased` is empty with a comment explaining what belongs there. Also adds a three-line pointer from the README's Development section to both new files. ## Notes for review - One convention encoded from practice rather than from an existing doc: CONTRIBUTING says not to add AI-assistant attribution trailers to commit messages. Drop that line if you'd rather not state it. - CONTRIBUTING deliberately contains no literal ticket-shaped example ID — the `public-repo-hygiene` scanner reads this file too. `node scripts/check-public-repo-hygiene.mjs` passes on the branch. - No dependencies were installed to produce this, so the pnpm-based checks were not run locally; nothing here is TypeScript, and `.github/dependabot.yml` and both templates' front matter were parsed to confirm they are valid YAML. - AGENTS.md is intentionally absent — it's being added separately. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 22:04:14 +00:00