start upgrade guide, and add pieces from LegolasFlux upgrade

docs/make.jl

@@ -7,7 +7,8 @@ makedocs(modules=[Legolas],
          pages=["API Documentation" => "index.md",
                 "Schema-Related Concepts/Conventions" => "schema-concepts.md",
                 "Arrow-Related Concepts/Conventions" => "arrow-concepts.md",
-                "FAQ" => "faq.md"])
+                "FAQ" => "faq.md",
+                "Upgrading from v0.4 to v0.5" => "upgrade.md"])
 
 deploydocs(repo="github.com/beacon-biosignals/Legolas.jl.git",
            push_preview=true,

docs/src/upgrade.md

@@ -0,0 +1,16 @@
+# Upgrading from Legolas v0.4 to v0.5
+
+This guide is incomplete; please add to it if you encounter items which would help other upgraders along their journey.
+
+## Some main changes to be aware of
+
+* In Legolas v0.4, every `Legolas.Row` field's type was available as a type parameter of `Legolas.Row`; for example, the type of a field `y` specified as `y::Real` in a `Legolas.@row` declaration would be surfaced like `Legolas.Row{..., NamedTuple{(...,:y,...),Tuple{...,typeof(y),...}}`. In Legolas v0.5, the schema version author controls which fields have their types surfaced as type parameters in Legolas-generated record types via the `field::(<:F)` syntax in [`@version`](@ref).
+    * Additionally, to include type parameters associated to fields in a parent schema, they must be re-declared in the child schema. For example, the package LegolasFlux declares a `ModelV1` version with a field `weights::(<:Union{Missing,Weights})`. LegolasFlux includes an [example](https://github.com/beacon-biosignals/LegolasFlux.jl/blob/53c677848c6b65e5158ef2d43dd5f7eab174892e/examples/digits.jl#L78-L80) with a schema extension `DigitsRowV1` which extends `ModelV1`. This `@version` call must re-declare the field `weights` to be parametric in order for the `DigitsRowV1` struct to also have a type parameter for this field.
+* Constructors for structs generated by `@version` calls discard "extra" columns, whereas previously under Legolas v0.4, `@row`-generated constructors kept any "extra" columns. It may be advisable to add previously used "extra" columns into the schema itself (probably declared as `::Union{Missing,T}` to allow them to be missing).
+
+
+## Deserializing old tables with Legolas v0.5
+
+Generally, tables serialized with earlier versions of Legolas can be de-serialized with Legolas v0.5, making it only a "code-breaking" change, rather than a "data-breaking" change. However, it is strongly suggested to have reference tests with checked in (pre-Legolas v0.5) serialized tables which are deserialized and verified during the tests, in order to be sure.
+
+Additionally, tables with nested Legolas schemas (i.e. a row has a column whose elements are themselves Legolas rows) will need special handling to deserialize under Legolas v0.5. Recall that under Legolas v0.4, row types can contain arbitrary "extra" columns not specified in the schema. Under Legolas v0.5, their analog, namely structs created by the `@version` macro, only allow columns specified in their schema. Therefore, one must decide what to do with any "extra" columns when deserializing older tables, and use the constructor to old Legolas rows to the new types. For example, [this LegolasFlux example](https://github.com/beacon-biosignals/LegolasFlux.jl/blob/53c677848c6b65e5158ef2d43dd5f7eab174892e/examples/digits.jl#L64-L84) uses a function `compat_config` to handle old Legolas rows, but does not add any handling for "extra" columns, which will be discarded if present. In that scenario, extra columns could be handled by throwing an error, a warning, or expanding the schema (e.g. with `extras::Union{Missing, NamedTuple}`).