Create document describing our versioning policy

[pjohnmeyer]

As discussed at multiple TWGs and in issue discussions such as this one, we would like to explicitly define our versioning policy. This would be based on semantic versioning. We do, however, want to create a distinction between the "interface" and "implementation" parts of our schema, so that we have the flexibility to change folder structure, layouts, general approaches, etc., while maintaining stability. The proposal on the table is to: maintain all files and objects $ids through the duration of 1.0; users of the schema are "allowed" to reference those IDs directly and expect the only thing to change is the version number. Anybody directly referencing the $id of a schema under enums, primitives, or types is bypassing the "interface" of the schema and is subject to potential breakage.

[JSv4]

Some rules:

To avoid breaking

• Can't rename
• Can't make required where it wasn't
• Can't change the data type

We CAN re-arrange. But we can't change the $ids for files and objects.

[pjohnmeyer]

Question for the TWG: Does improving schema rules, without REQUIRING a new field or RENAMING a field, count as a breaking change?

It would cause validation to pass on version 1.a but fail on version 1.b, so my tendency is to say that "yes this is a breaking change" -- but enhancing validation is also a meaningful improvement.

For example:

https://github.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF/wiki/Planned-2.0-Rework#dont-allow-converts_to_stock_class_id-and-converts_to_future_round-true-on-the-same-conversion-right

https://github.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF/blob/5848a7e63dc06018031d54bff2e04be39d3af9ec/schema/primitives/types/conversion_rights/ConversionRight.schema.json#L35-L42

If we were to add a clause here that says "converts_to_future_round is true then converts_to_stock_class_id should not be present" -- would that be a breaking change?

[JSv4]

In process

[JSv4]

Hey @pjohnmeyer, since this came up on our call again today - e.g. what's a breaking change - do you want to revisit this? No pressure, I just remember you were thinking about this earlier, and if you have a good starting point for this, would be great to get this up into the docs.

[JSv4]

Couple points:

• Want to be free to rename things that aren't in upper-level interface, but we want to otherwise be able to refactor.
• If there is a bug or otherwise unusable schema, we probably don't want that to be a major version, but technically would be under above point.
  • Do we want to distinguish between things that are actually in a release vs just in main?