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.
38 lines
1.4 KiB
Markdown
38 lines
1.4 KiB
Markdown
---
|
|
title: OpenAPI Commit Guidelines
|
|
weight: 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][gitea]) 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**.
|
|
|
|
[gitea]: https://projects.blender.org/studio/flamenco/
|
|
{{< /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:
|
|
|
|
1. Commit the changes to `pkg/api/flamenco-openapi.yaml`, prefixing the commit
|
|
message with `OAPI:`.
|
|
2. Regenerate code with `make generate`, then commit with message
|
|
`OAPI: Regenerate code`.
|
|
3. 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.
|