Edit Safety¶
Source: hooks/ways/softwaredev/code/quality/edit-safety/edit-safety.md
Frontmatter
| Field | Value |
|---|---|
description |
fixing something in generated code or output, such as an API client built from an OpenAPI or swagger spec, protobuf or grpc stubs, ORM models or a built site; edit the source and regenerate instead of hand-editing the output, carry existing hand edits back to the source, and when someone else is editing the same file, re-read it right before the edit and keep their changes |
vocabulary |
generated file autogenerated generated code codegen generator do not edit header regenerate rerun the generator source spec template openapi swagger protobuf grpc stubs sdk client orm models build folder hand edit overwritten by the next build teammate editing the same file at the same time clobber |
pattern |
\bcodegen\b|auto.?generated |
files |
(^|/)(generated|generated)/|.(pb|gen|generated).\w+$|_pb2(_grpc)?.py$ |
refire |
0.2 |
scope |
agent, subagent |
An edit made against a stale picture of a file loses work. The next build overwrites a hand edit to generated output, or the save drops changes someone made after you read the file.
Generated files¶
- Before editing a file, check whether a generator owns it: a "generated, do not edit" header, a path under a generated directory, a schema, spec, template or build script that writes it.
- Edit the source and rerun the generator. The next build erases a hand edit to the output without warning.
- When someone has already hand-edited the generated file, diff their edits before regenerating and carry each one into the source.
- Do not overwrite a dated output that a report or link points to. Generate a new one.
Files someone else is editing¶
- Re-read the file from disk right before the edit. A read from earlier in the session may be stale.
- Keep the other person's changes. Make the edit without reformatting or reordering their parts, and find records by key, not by line position.
- Uncommitted changes in the working tree: delivery/commits/prepare.
- When your edit would land in the region they are changing, say so and agree on an order before saving.
Common Rationalizations¶
| Rationalization | Counter |
|---|---|
| "I read the file a few turns ago" | It may have been saved since. Read it again before the edit. |
| "Fixing the generated file is faster" | The next build erases the fix. Change the source. |
| "Git has the old version" | Only what was committed. Uncommitted work exists in one place. |
See Also¶
- code/quality/integration(softwaredev) — the class sweep, including a generated file per consumer
- meta/subagents/agent-teams(meta) — several agents in one checkout
- delivery/commits/prepare(softwaredev) — uncommitted changes you did not make, and staging by name
- delivery/patches(softwaredev) — patches generated from real file changes
- freshness(softwaredev) — generated files that fell behind their source