From 198880f6c2ab7957c06902a6d06f4147c9e9bed7 Mon Sep 17 00:00:00 2001 From: Honza Dvorsky Date: Wed, 16 Aug 2023 13:12:01 +0200 Subject: [PATCH] [Docs] Clarify what constitutes a breaking change of generated code (#200) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [Docs] Clarify what constitutes a breaking change of generated code ### Motivation As new features are introduced to the generator, it is limiting to not be able to add new defaulted properties to generated structs without it being an API-breaking change. ### Modifications Clarify that adding a defaulted property to a generated struct is not considered a breaking change in the Swift OpenAPI Generator project, and adopters should avoid capturing initializers of generated structs for that reason. ### Result With this clarification, we can add new defaulted properties without breaking API. ### Test Plan N/A Reviewed by: glbrntt Builds: ✔︎ pull request validation (5.8) - Build finished. ✔︎ pull request validation (5.9) - Build finished. ✔︎ pull request validation (docc test) - Build finished. ✔︎ pull request validation (integration test) - Build finished. ✔︎ pull request validation (nightly) - Build finished. ✔︎ pull request validation (soundness) - Build finished. https://github.com/apple/swift-openapi-generator/pull/200 --- .../Articles/API-stability-of-generated-code.md | 2 +- .../Articles/API-stability-of-the-generator.md | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-generated-code.md b/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-generated-code.md index 81bba3d1..f308a646 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-generated-code.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-generated-code.md @@ -27,7 +27,7 @@ Below is a table of example changes you might make to an OpenAPI document, and w | Remove a required property | ❌ | ❌ | ❌ | | Rename a schema | ✅ | ❌ | ❌ | -> †: Safe change to make as long as no adopter captured the Swift function signature of the initializer of the generated struct, which gains a new parameter. Rare, but something to be aware of. +> †: Safe change to make as long as no adopter captured the Swift function signature of the initializer of the generated struct, which gains a new parameter. Rare, but something to be aware of. Note that when upgrading the generator to a newer version, we reserve the right to add new defaulted properties to generated structs, so such a change is considered non-breaking. For that reason, avoid capturing the function signature of the initializer of any generated struct. > ‡: Adding a new response to an existing operation introduces a new enum case that the adopter needs to handle, so is a breaking change in OpenAPI and Swift. diff --git a/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md b/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md index 10d5ec9c..99617501 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md @@ -6,7 +6,14 @@ Understand the impact of updating the generator package plugin on the generated Swift OpenAPI Generator generates client and server Swift code from an OpenAPI document. The generated code may change if the OpenAPI document is changed or a different version of the generator is used. -This document outlines the API stability goals for the generated code to help you avoid unintentional build errors when updating to a new version of Swift OpenAPI Generator. +This document outlines the API stability goals for the generator to help you avoid unintentional build errors when updating to a new version of Swift OpenAPI Generator. + +The components covered by these rules are: +- the name of the Swift OpenAPI Generator package plugin +- the format of the config file provided to Swift OpenAPI Generator (plugin or CLI tool) +- the Swift OpenAPI Generator CLI tool arguments + +If you upgrade any of the components above to the next non-breaking version, your project should continue to build successfully. Check out how these rules are applied before 1.0 is released, and what a breaking change means for the generated code: . ### API stability for versions >= 1.0.0