92a93bb4d7
Found via `codespell -S "*.po,*.chunk.min.js" -L cace,cacl,currenty,eacf,eacg,fo,nd,nin,ontext,originaly,ot,te,ue` No functional changes. Co-authored-by: Sybren A. Stüvel <sybren@blender.org> Pull Request: https://projects.blender.org/studio/flamenco/pulls/104436
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 **committed 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.
|