search

Open-Cap-Table-Coalition / Open-Cap-Format-OCF

Open Cap Format (OCF) - The Open Source Company Capitalization Data Standard. OCF can be used to structure and track the complex data structures necessary to build and maintain accurate capitalization (cap) tables.
https://opencaptablecoalition.com
Other
139 stars 26 forks source link

Create document describing our versioning policy #416

Open pjohnmeyer opened 1 year ago

pjohnmeyer commented 1 year ago

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 commented 1 year ago

Some rules:

To avoid breaking

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

pjohnmeyer commented 1 year ago

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 commented 1 year ago

In process

JSv4 commented 5 months ago

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 commented 4 months ago

Couple points: