Skip to content

Commit 1b37b9a

Browse files
chore: enforce generated-file ownership (#4193)
Retire generated-file customization budgets and rely on `AGENTS.md`, contributor guidance, and ordinary code review for ownership. Generated files must not carry handwritten edits: fix the inputs/compiler and regenerate; put custom behavior in separately owned handwritten extensions. This combines normal Castiron-regenerated cleanup with SDK-owned documentation. It removes the budget reporters, workflows, zero-only policy, and the proposed dedicated file checker. There is no dedicated generated-file edit gate for now. The compiler replaces generated output and deletes retired paths without three-way replay. The retired budget status requirements are removed and their producers disabled across public/private SDKs. Normal SDK checks, CODEOWNER review, generation/promotion provenance, and release pins remain. Generated output and inventory changes should be reviewed together. Validation: documentation and workflow diffs checked; the unchanged generated output still matches normal generation. Relevant formatting and focused entrypoint/layout tests pass. Two consecutive independent review rounds and current-head CI are tracked for this revision. --------- Co-authored-by: jbeckwith-oai <269036200+jbeckwith-oai@users.noreply.github.com>
1 parent 23a6be4 commit 1b37b9a

26 files changed

Lines changed: 49 additions & 12421 deletions

‎.castiron-ratchet.json‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎.castiron.stats.yml‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
schema_version: 1
2-
generation_id: 5bb155ba-0fb6-4563-a504-851ce952578c
2+
generation_id: 3979ac4c-7176-4e6d-9fde-1b9fa94dca0e
33
openapi_spec_hash: 2c78c708cab402e8904f555026c78020
44
openapi_transformed_spec_hash: e513b495f24d8119b952521ffc783d86
55
config_hash: e8e4d0a0f7d89bb89f18f5ed789c0ac6
6-
codegen_sha: f2b8c4107e23c8d9c2431903533c975f5cfcd342
7-
codegen_hash: d7afe679f4861d8aec19f61fefe2c0659d30cc557923b3614ca142d5985d5a4f
8-
public_codegen_sha: ebb8cc5c28762f6527f4d2ae5c96e21f4d4050b3
6+
codegen_sha: 47c0bc8105b4986bef09e3e9e43ab8a26cd882c9
7+
codegen_hash: a0d517f4d93e3430ed6dbcf2dfb9aeba57e563f1b7348a093d149c3d6c20ea77

‎.github/workflows/castiron-custom-code-comment.yml‎

Lines changed: 0 additions & 904 deletions
This file was deleted.

‎.github/workflows/castiron-custom-code.yml‎

Lines changed: 0 additions & 116 deletions
This file was deleted.

‎AGENTS.md‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,21 @@ changing generated files. Handwritten policy, automation, tests, and examples
77
should remain small and should not alter exported SDK APIs unless the change
88
explicitly requires it.
99

10-
## Custom-code budget
11-
12-
Follow [the custom-code guidance](scripts/castiron/CUSTOM_CODE.md). Budget changes
13-
belong in a separate PR containing only `.castiron-ratchet.json`, with an explicit justification
14-
in the PR description. Increases require a **human approving review** before merging.
15-
Agents may investigate and draft proposals, but must not approve budget increases
16-
(including through a human's credentials) or bypass the gate. Do not weaken
17-
counting, broaden exclusions, or alter generation metadata to make a change pass.
18-
The checker and effective budget come from main, not the PR. Keep default CODEOWNERS.
10+
## Generated-file ownership
11+
12+
Never hand-edit generated SDK files, including generated tests, documentation,
13+
workflows, or the generated-file inventory. Change the authoritative API schema,
14+
configuration, or compiler, then regenerate. Put SDK-specific behavior in
15+
separately owned handwritten helpers and extension points.
16+
17+
Regeneration replaces generator-owned files and deletes retired generated paths.
18+
Handwritten edits to generated files are overwritten; they are never replayed or
19+
merged into new output. Preserve separately owned handwritten files and resolve
20+
ownership collisions explicitly. Follow this AGENTS.md rule and review generated output and inventory changes
21+
together. Generated-file ownership currently relies on contributor guidance and
22+
code review; there is no dedicated generated-file edit check or required gate.
23+
Fix violations in the inputs/compiler and regenerate; never update inventory
24+
hashes to accept a handwritten patch.
1925

2026
## Security requirements for coding agents
2127

‎CONTRIBUTING.md‎

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -96,26 +96,25 @@ and [Dependabot's cooldown policy](https://docs.github.com/en/code-security/refe
9696

9797
## Modifying/Adding code
9898

99-
Most of the SDK is generated code. Modifications to code will be persisted between generations, but may
100-
result in merge conflicts between manual patches and changes from the generator. The generator will never
99+
Most of the SDK is generated code. Never edit generated files by hand; change
100+
the authoritative generation inputs or compiler and regenerate instead. The generator will never
101101
modify the contents of the `src/openai/lib/` and `examples/` directories.
102102

103-
## Custom-code budget
104-
105-
The custom-code budget counts additions plus deletions in the remaining patch
106-
against verified generated output. `.castiron-ratchet.json` defines this repository's
107-
ceiling. CI uses the checker and budget on main, not the PR's proposed versions.
108-
109-
Budget changes must be in a separate PR modifying **only `.castiron-ratchet.json`**.
110-
Justify the current usage, proposed ceiling, and why fixing generation is not
111-
appropriate in the PR description. Increases require a **human approving review**
112-
and must merge before an SDK change relies on them. Agents may draft proposals,
113-
but must not approve increases or bypass the gate. Keep default CODEOWNERS.
114-
Lower the ceiling after cleanup while retaining headroom; decreases must still
115-
fit the measured usage.
116-
117-
See [custom-code technical details](scripts/castiron/CUSTOM_CODE.md) for accounting,
118-
local checks, trusted CI, and activation instructions.
103+
## Generated-file ownership
104+
105+
Do not edit generated SDK files by hand. Fix the API schema, generation
106+
configuration, or compiler and regenerate instead. Put SDK-specific behavior in
107+
separately owned handwritten helpers and extension points.
108+
109+
Regeneration replaces generated files and removes retired generated paths.
110+
Handwritten edits to generated output are overwritten, not carried forward.
111+
Separately owned handwritten files are preserved. Resolve ownership conflicts
112+
explicitly before regeneration. Follow the ownership rules in `AGENTS.md`
113+
and review generated output and inventory changes together. Generated-file
114+
ownership currently relies on contributor guidance and code review, without a
115+
dedicated generated-file edit check or required gate. Fix violations in the
116+
generation inputs/compiler and regenerate; do not edit inventory hashes to
117+
accept a handwritten patch.
119118

120119
## Security requirements for contributions
121120

0 commit comments

Comments
 (0)