start upgrade guide, and add pieces from LegolasFlux upgrade

[ericphanson]

when @kleinschmidt and I upgraded LegolasFlux to Legolas v0.5, we encountered several points that we thought would be useful to as upgrade guidance for our users. All of those points seem general and not specific to LegolasFlux however, so I think it would be more appropriate to put it in Legolas's documentation itself.

This adds incomplete documentation (since I don't think this is a full upgrade guide), but it is deliberately called out as such. IMO it would be better to incrementally add pieces as folks find things rather than block such guidance on being complete.

ref #57

[kleinschmidt]

looks good with one little quibble! I agree this is a good place for it to live

[hannahilea]

:glue: ❤️ :teamwork-makes-the-dreamwork:

[jrevels]

LGTM pending folding in suggestions!

[jrevels]

not sure i understand the "an example of a comprehensive log of changes" change (it's not an example of a changelog, it's just the changelog that accompanies the PR) but doesn't matter either way lol

[ericphanson]

not sure i understand the "an example of a comprehensive log of changes" change (it's not an example of a changelog, it's just the changelog that accompanies the PR) but doesn't matter either way lol

Oh oops, somehow I thought that link pointed at beacon-biosignals/LegolasFlux.jl#21 as an upgrade example, in which case it wouldn't be a comprehensive log of changes to this package. But I see the link points to #54, which makes more sense, and the wording made sense as-is.

[jrevels]

just realized it might be mildly useful for me to provide slightly more context on my thought process for one of the suggested changes we folded in (and to surface for lurkers who might've missed the nested suggestion in the first place)

- 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).
+ In Legolas v0.4,  `@row`-generated `Legolas.Row` constructors accepted and propagated any 
+ non-schema-required fields provided by the caller. In Legolas v0.5, `@version`-generated record 
+ type constructors will discard any non-schema-required fields provided by the caller. When upgrading 
+ code that formerly "implicitly extended" a given schema version by propagating non-required fields, it 
+ is advisable to instead explicitly declare a new extension of the schema version to capture the propagated 
+ fields as required fields; or, if it makes more sense for a given use case, one may instead define a new 
+ schema version that adds these propagated fields as required fields directly to the schema (likely 
+ declared  as `::Union{Missing,T}` to allow them to be missing).

tidbits to draw attention to:

• subtle nitpick, but since legolas doesn't really do anything at the table-level yet (besides validating the values/types of a table's rows), i defensively try to always use "fields" instead of "columns" just to avoid confusion (though the latter isn't necessarily incorrect depending on your perspective)

• the former advice could be misunderstood to mean "add a new required field to an existing schema version" (though it might not have intended that) but doing so would be a breaking change which necessitates a schema version bump

• generally the preferred path in Legolas v0.5 is to translate implicit/dynamic extensions into explicit/static extensions wherever reasonable, though in some cases introducing that might entail a tradeoff between "thrust things into the Right Way on Legolas v0.5" and the amount of breakage you're willing to propagate that may or may not be worthwhile depending on the scenario