Skip to content

Commit

Permalink
[Docs] Clarify what constitutes a breaking change of generated code (#…
Browse files Browse the repository at this point in the history
…200)

[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. 

#200
  • Loading branch information
czechboy0 authored Aug 16, 2023
1 parent 722c1ab commit 198880f
Show file tree
Hide file tree
Showing 2 changed files with 9 additions and 2 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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: <doc:API-stability-of-generated-code>.

### API stability for versions >= 1.0.0

Expand Down

0 comments on commit 198880f

Please sign in to comment.