01a97862db
Since the introduction of a `.gitattributes` file, tooling (like Gitea) is aware of which files are generated. This means that all OpenAPI-related changes (`pkg/api/flamenco-openapi.yaml`, re-generated code, and changes to the implementation) can be commited together. The downside is that tooling that is not aware of `.gitattributes` will still show a big mix of hand-crafted and generated changes. The upside is that each commit brings Flamenco from a valid, runnable state to another valid, runnable state. This helps greatly when investigating history (like bisecting) to find the source of a bug.
1.4 KiB
| title | weight |
|---|---|
| OpenAPI Commit Guidelines | 30 |
{{< hint type=Warning >}} The guideline below has been obsolete since August 2025. It will be kept here for a while for historical reference.
Since the introduction of a .gitattributes file, tooling (like
projects.blender.org) is aware of which files are generated. This means
that all changes (pkg/api/flamenco-openapi.yaml, re-generated code, and
changes to the implementation) can be commited together.
{{< /hint >}}
Typically a change to the OpenAPI definition consists of three steps, namely making the change to the OpenAPI file, regenerating code, and then alter whatever manually-written code needs altering.
Each of these steps should be committed independently, by following these steps:
- Commit the changes to
pkg/api/flamenco-openapi.yaml, prefixing the commit message withOAPI:. - Regenerate code with
make generate, then commit with messageOAPI: Regenerate code. - Commit any other code changes to complete the change.
The downside to this approach is that the second commit will likely break the project, which is unfortunate. However, this approach does have some advantages:
- The regenerated code has the right Flamenco version number.
- Changes to manually-written and generated code are tracked in separate commits. This makes them easier to comprehend by humans.