Guidelines for incrementing the config part of the version string

[doug-walker]

The name of the configs contains a string with three versions. For example: cg-config-v1.0.0_aces-v1.3_ocio-v2.1. It is self-evident what the ACES and OCIO versions should contain but the guidelines for when to increment the config part have not been documented. The following guidelines are proposed as a strawman for further discussion:

Major version increment:

• Adding color spaces
• Adding displays

Minor version increment:

• Adding looks
• Adding new views to existing displays
• Adding named transforms
• Role changes
• Significant changes to existing transforms
• Changes to aliases

Patch version increment:

• Removing color spaces, displays, views, if they are kept in the inactive list
• Minor changes to existing transforms
• Changes to description text
• Changes to family, categories, encoding
• Changes to file_rules or viewing_rules
• Changes to active_displays, active_views, inactive_colorspaces
• Changes to default_view_transform

I'm on the fence about some of these. In many cases it could be a matter of degree (was it a big change or a small change) and so it's difficult to come up with absolutely fixed rules. Therefore, it seems prudent to refer to these as "guidelines" rather than "rules" to indicate that in some cases there will be a judgment call made by the configs working group on how to assign a new version string.

[KelSolaar]

Hey @doug-walker,

Any particular reasons for not trying to fly closer to SemVer? e.g. additions of new colourspaces and displays are Minor but changes to transforms are Major?

[doug-walker]

@KelSolaar , thanks for the feedback. (The above is just a strawman for discussion and so I'm open to changing any of it.)

The rationale for incrementing the major version when color spaces are added is that the new config could not be interchanged with the previous one without risk of an error. Regarding changes to the transforms, I think whether it's major or minor would be a judgment call about what actually changed. For example, if it's a small change to an entry in a remote part of a 3d-LUT, maybe that's only a minor / bug-fix type of version increment.

[doug-walker]

The working group discussed this during the 2023-08-29 meeting. Here is what I captured as a summary:

• Breaking changes such as changing or removing something significant requires a major bump (e.g. role changes, though not additions, require a major config version bump)
• Adding color spaces or roles could be a minor version update
• All configs having the same configs version should have the same content (so going forward, bumping the OCIO version will not be used to indicate that color spaces/looks may vary)

[KelSolaar]

Here is a first pass for a table as discussed during the meeting:

Major Version Increase	Minor Version Increase	Patch Version Increase
Remove Colorspace	Add Colorspace	Add Colorspace to inactive_colorspaces
Remove Look	Add Look	Add Look to inactive_colorspaces
Remove NamedTransform	Add NamedTransform	Add NamedTransform to inactive_colorspaces
Remove DisplayColorspace	Add DisplayColorspace	Add DisplayColorspace to inactive_colorspaces
Remove ViewTransform / SharedView	Add ViewTransform / SharedView
Remove Role	Add Role
Reassign Role
Change to Transform Processing Output		Fix Incorrect Transform Processing Output?
Remove alias from aliases	Add alias to aliases
Remove AMF component	Add AMF component
		Change to categories
		Change to encoding
		Change to family
		Change to Transform Description
		Change to Config Description
		Change to file_rules
		Change to viewing_rules
		Change to active_displays
		Change to active_views
		Change to inactive_colorspaces
		Reassign default_view_transform
Change luma?

You can load the table here and continue editing if needed: https://www.tablesgenerator.com/markdown_tables