Re: [calsify] JSContact and Versioning

[Michael Douglass <[e-mail]>]

A bit late in the day again...

I think we should mandate at least an official versioning scheme rather 
than just a simple incrementation.

As developers we already have a example of how that might work e.g. 
<major>.<minor>.<patch>.<extension>*

Without specifying exactly what triggers a change in those numbers (or 
any other scheme) - we're going to have to assume the worst at each change.

I would suggest something like -

1. An non-backward compatible change requires incrementing <major>. e.g. 
we remove a property and replace it with a differently named property, 
or we change the specification of a property enough that it would break 
implementations.

2 Update minor when properties are added (and possibly removed) and 
ignoring the added property does not result in an invalid object

3. Update patch when?

I was going to suggest that just <major> could be valid as could be 
<major>.<minor>. However that can led to some weird contortions.

<extension>* is a suggestion to get around some of the odd versioning in 
maven - it would allow a suffix to be added to indicate the version of 
proprietary extensions

I guess it's clear that a monotonically increasing version is a must.

I think this means that i think the last point needs to be changed. It's 
not up to those registering to bump the value(s) but it should be made a 
requirement of any review - otherwise - what encourages 
developers/software to check for changes?

Maybe the 3rd value could be bumped when a new property is added and the 
minor value updated after it goes through expert review


On 12/7/22 05:42, Robert Stepanek wrote:
> We would like to revisit versioning in JSContact and would appreciate 
> your feedback before end of WGLC. Specifically, we plan to change the 
> currently proposed version scheme such that:
>
>   * Rather than using the RFC number as a version, we propose to use
>     version strings that are independent from the RFC numbering
>     scheme. We define the initial JSContact version to be "1", but we
>     also explicitly state that for now the only thing implementations
>     can rely on is that future version values lexicographically sort
>     after former ones. In a future JSContact RFC we might introduce a
>     more sophisticated version scheme.
>   * We replace the current "Version" field in the IANA registration
>     templates with "Minimum Version" and "Maximum Version", such that
>     the IANA registry is enough to identify which properties or values
>     are supported in which versions. They can then follow the
>     according RFC references in the same registry.
>
>
> Also, we'll slightly rephrase the RFC document section about 
> versioning. The following bullets paraphrase what we intend to define. 
> Most of this already is in the current document, but it might be 
> simpler to review here as a whole:
>
>   * Version changes may add new property and value definitions that
>     are so significant that implementations should be made aware of
>     their presence by only inspecting the version value. This can be
>     useful for protocols to allow clients or servers to advertise
>     which JSContact version they are able to process, or to select one
>     of multiple MIME body parts with JSContact data by version.
>   * Version changes may obsolete or update existing property and value
>     definitions such that they are incompatible with their definitions
>     of earlier versions. This should always be the last tool in the
>     box, but introducing versions now hopefully allows us to handle
>     these situations in the future.
>   * Version changes always require a RFC that defines the impact on
>     future JSContact version.
>   * Not every new property or value definition that gets registered at
>     IANA requires to change the version. The majority of changes
>     should not, because we want to encourage people to register their
>     JSContact additions. Since our IANA-registration policy is Expert
>     Review, it's always up to the discretion of the designated experts
>     if the proposed additions require a RFC document or JSContact
>     version bump.
>
>
> Cheers,
> Robert
>
> _______________________________________________
> calsify mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/calsify