0.17.0 Changelog draft [ci-skip]

CHANGELOG.md

@@ -0,0 +1,65 @@
+# 0.17.0
+
+This 0.17.0 release of Smithy4s brings a number of improvements on the abstractions implemented by the generated code, in particular in terms of flexibility and user experience.
+
+This release also aims at brining inter-operability with other tools that Disney Streaming is putting forward to reinforce the Smithy ecosystem, such as [smithy-translate](https://github.com/disneystreaming/smithy-translate/).
+
+In order to achieve these improvements, we've had to break a number of things at different levels. This release is therefore neither source nor binary compatible with the previous ones, and also forces the user to update their Smithy specifications.
+
+## Breaking changes
+
+### Smithy-level breaking changes
+
+See https://github.com/disneystreaming/smithy4s/pull/561
+
+The smithy shapes that were previously residing under `smithy4s.api` namespace have moved to the `alloy` namespace. Alloy is a standalone library containing smithy shapes and validators, defined [here](https://github.com/disneystreaming/alloy).
+
+The reason for us to bring this change is to have a language specific location to define shapes that are relevant to the protocols/runtime-behaviours we're putting forward, that could be used by tooling working with other languages than Scala. It was important for us to lose the `4s` suffix, which is short for `for Scala`.
+
+This change implies, for instance, that any use of `smithy4s.api#simpleRestJson` in your specification will have to be replaced by `alloy#simpleRestJson`.
+
+### Build-plugins breaking changes (SBT/mill)
+
+#### Multiple input directories
+
+See https://github.com/disneystreaming/smithy4s/pull/587
+
+The `smithy4sInputDir` setting/task in SBT/mill has been replaced by `smithy4sInputDirs`, allowing the user to set several directories where the plugins should look for smithy files
+
+#### Change in smithy-library dependency resolution
+
+See https://github.com/disneystreaming/smithy4s/pull/607
+
+We've changed the smithy-sharing mechanism to do two things :
+
+1. By default, any dependency declared "normally" in SBT or mill, by means or `libraryDepedencies ++=` or `def ivyDeps`, will be inspected for Smithy files after being resolved. This means that, for instance, if your application has a runtime dependency on a library that was built with Smithy4s and contains Smithy files, your local specs can use the code defined in these Smithy files to create or annotate new shapes. You no longer need to declare those using `% Smithy4s` or `def smithy4sIvyDeps` : these are now reserved for libraries containing Smithy files that you **do not want your application's runtime to depend on**.
+2. Libraries built by Smithy4s automatically track the dependencies that they used during their own code-generation, by storing some metadata in their Jar's manifests. By default, the Smithy4s plugins will also pull those dependencies (which will have been declared upstream using `% Smithy4s` in SBT or `def smithy4sIvyDeps` in mill), for your project's code generation. This facilitates the transitivity of specification-holding artifacts. This mechanism is used, for instance, to communicate to users projects the fact that Smithy4s depends on shapes that are defined in the [alloy](https://github.com/disneystreaming/alloy) library, and that these shapes should be made available to user projects, without impacting the user's application runtime, and without requiring any setup from the user.
+
+### Normal-usage breaking changes in the generated code
+
+See https://github.com/disneystreaming/smithy4s/pull/599
+
+Depending on your setup, it may be a breaking change, but `@deprecated` Smithy-traits now translate to the `@deprectated` Scala annotation in the generated code.
+
+### Normal-usage source breaking changes
+
+See https://github.com/disneystreaming/smithy4s/pull/569
+
+If you use Smithy4s in the ways that were previously advertised in the documentation, you may have to perform some small adjustments.
+
+In particular, the `simpleRestJson` extension method that was added to implementations of service-interfaces generated by Smithy4s is now deprecated, in favour of the `SimpleRestJsonBuilder` construct (which now works for any `service` smithy shape that will have been annotated with `alloy#simpleRestJson`).
+
+### Advanced usage breaking changes
+
+The abstractions that the generated code implements and that the runtime interpreters use have undergone some massive chances.
+
+#### Unification of the natural-transformations/polymorphic functions.
+
+* Smithy4s makes a lot of use of polymorphic functions of various kinds. Those are now code-generated (see the `project/Boilerplate.scala` file) to ensure the consistency of the various ways they are being used. This means that `smithy4s.PolyFunction` has moved to `smithy4s.kinds.PolyFunction`, and that the previous `smithy4s.Transformation` is now `smithy4s.kinds.PolyFunction5`. This decision ripples in the `smithy4s.Service` interface, which now sports `toPolyFunction` and `fromPolyFunction` methods, allowing to turn a finally-encoded implementation into a final one. `smithy4s.kinds.PolyFunction2` is also a thing, and may be used in bi-functor contexts.
+* `kind`-specific types were created to facilitate the "lift" of constructs to the right kinds. For instance, one inspecting the internals of this library might see things like `Kind1[IO]#toKind5` where in was previously `GenLift[IO]#λ`. We're hoping to convey meaning better, although this code is definitely still not trivial (and never will).
+* `smithy4s.Transformation` is now a typeclass-like construct, which expresses the fact that a construct can be applied on another like a function. This construct is used by the `transform` method that is generated on service interfaces, which allows to apply custom behaviour generically on all method invocations in these interfaces.
+* The `Service` interface takes a single `Alg` type parameter, the `Op` parameter has moved to type-member position, facilitating implicit search in some contexts (as well as the writing of some logic).
+* A bunch of path-dependant type-aliases were created in the `Service` interface.
+* The `compliancetest` module has changed drastically in UX. For those not aware, this module allows to run tests written in Smithy against your own implementation of protocols. This will be useful for third-party libraries that implement `simpleRestJson` (or any other http/rest like protocol), to virtually get tests for free. We don't think this module had any users so far, but we'll slowly be porting some of our tests away from the `smithy4s` repository and into the `alloy` repository.
+
+## User facing improvements