Skip to content

Commit 0309a8c

Browse files
docs: clarify generated-file ownership (#4241)
Consolidate generated-file ownership guidance in the contributor guide and link to it from `AGENTS.md`. Explain how to trace a fix to the API schema, SDK generator, or a handwritten file, with a repository-specific example. Verified the documentation links and section anchors and ran `git diff --check`.
1 parent 5f717b5 commit 0309a8c

2 files changed

Lines changed: 8 additions & 32 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,7 @@ explicitly requires it.
99

1010
## Generated-file ownership
1111

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.
12+
Follow [Modifying/Adding code](CONTRIBUTING.md#modifyingadding-code) to identify the source of a fix before editing SDK files.
2513

2614
## Security requirements for coding agents
2715

‎CONTRIBUTING.md‎

Lines changed: 7 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -99,25 +99,13 @@ and [Dependabot's cooldown policy](https://docs.github.com/en/code-security/refe
9999

100100
## Modifying/Adding code
101101

102-
Most of the SDK is generated code. Never edit generated files by hand; change
103-
the authoritative generation inputs or compiler and regenerate instead. The generator will never
104-
modify the contents of the `src/openai/lib/` and `examples/` directories.
105-
106-
## Generated-file ownership
107-
108-
Do not edit generated SDK files by hand. Fix the API schema, generation
109-
configuration, or compiler and regenerate instead. Put SDK-specific behavior in
110-
separately owned handwritten helpers and extension points.
111-
112-
Regeneration replaces generated files and removes retired generated paths.
113-
Handwritten edits to generated output are overwritten, not carried forward.
114-
Separately owned handwritten files are preserved. Resolve ownership conflicts
115-
explicitly before regeneration. Follow the ownership rules in `AGENTS.md`
116-
and review generated output and inventory changes together. Generated-file
117-
ownership currently relies on contributor guidance and code review, without a
118-
dedicated generated-file edit check or required gate. Fix violations in the
119-
generation inputs/compiler and regenerate; do not edit inventory hashes to
120-
accept a handwritten patch.
102+
Look up the repository-relative path in the [Castiron generated-file inventory](scripts/castiron/generated-files.json). To [report a bug](#contribution-policy), include the SDK version, affected call, and a small, sanitized reproduction.
103+
104+
- **Incorrect API field.** If the API schema gives a field the wrong type or marks it required incorrectly, fix the schema and regenerate the SDK.
105+
- **Incorrect generated code.** If the schema is correct but the SDK exposes the wrong type or sends the wrong value, fix the generation configuration or compiler and regenerate. Verify the fix with a regression test that calls the public SDK.
106+
- **Handwritten helper or example.** Keep SDK-specific extensions in handwritten files and test them directly. For instance, [_realtime.py](src/openai/lib/_realtime.py) is handwritten. The [examples directory](examples/) contains handwritten examples.
107+
108+
Regeneration replaces owned files, including generated tests, docs, and workflows, and removes retired paths. Review the output and inventory together. Resolve ownership collisions before regenerating. Never hand-edit generated output or its inventory. Maintainers enforce this policy in code review.
121109

122110
## Security requirements for contributions
123111

0 commit comments

Comments
 (0)