From 01a97862dbaa41833a1d075d293ae2600046b6cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Thu, 7 Aug 2025 10:45:16 +0200 Subject: [PATCH] Website: update OpenAPI commit guidelines 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. --- .../development/openapi-commit-guidelines/_index.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/web/project-website/content/development/openapi-commit-guidelines/_index.md b/web/project-website/content/development/openapi-commit-guidelines/_index.md index 64523a85..fad473cd 100644 --- a/web/project-website/content/development/openapi-commit-guidelines/_index.md +++ b/web/project-website/content/development/openapi-commit-guidelines/_index.md @@ -3,6 +3,19 @@ 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.