Versioning alternatives

[rphair]

So far the CIP editors have not been willing to impose a universal versioning requirement on CIPs mainly because of different treatments of "versioning" according to each application and CIP subject. We've only rejected the idea that a CIP Version: field should be added to the header (suggesting it should be described in the CIP text itself), and have left all definitions and applications of versioning to each CIPs author or maintainer.

Given this laissez-faire approach we have somehow missed the particular importance of versioning for CIP-0068. My own understanding (forgive me, I'm not a developer in this area) was:

• new asset name labels being added via CIP-0067 would define the set of labels being supported, so the recent addition of the 444 asset name label wouldn't cause any incompatibilities that a version "bump" would fix.
• there is a version defined in the datum part of the schema which appears to be set always to 1 which (I guess) shows that these datums all together establish a "version 1" of CIP-0068 as it exists now, even with the recent addition.

In the discussion for #494 I didn't see any calls by either @AndrewWestberg, @alessandrokonrad, or implemetor @mmahut to add an explicit versioning scheme, although it's come up after the fact that this would have been a good idea. (If that were explicitly suggested somewhere then please somebody link to it below.)

Whatever may have been missing in the CIP review & editing process is bracketed in the Discord discussion between here and here. There were some longer, prior discussions on Discord about versioning which I would really like to ensure at this point have not been interpreted as an indication that CIP editors are against versioning in general.

So this issue is to get input from all concerned parties to:

• (ASAP) decide the best way to update CIP-0068 to give @mmahut and other implementors a solid base for to support this standard;
• (maybe) decide on a versioning scheme for applicable CIPs, with semantic versioning being generally recommended (most recently by @KtorZ - cc @matiwinnetou);
• more fully consider, between authors and editors, whether this kind of support issue could be avoided in the future by enabling a Version: field in CIP headers;
• decide whether CIP versioning should be mandatory in any particular, well-defined cases... e.g. for CIPs which present anything like an "API" as e.g. CIP-0068 presents to Blockfrost;
• (finally) list whatever precise rules can be used to update CIP-0001 accordingly.

Since I've been the main responder to the latest general questions about CIP versioning, I will keep trying to bring in prior discussions on the matter and will keep referring authors & reviewers here to get as broad a consensus as possible.

Please also tag any concerned parties and feel free to re-post any prior discussions or perceived omissions here, to be sure we make a full inventory of everyone's opinions and requirements.

[AndrewWestberg]

Since some people have already implemented parsing for CIP-68, I would recommend that we bump the version to 2 for the version that also supports the 444 prefix.

For most of these CIP standards, I would think semver is probably overkill. You'd have to store it in a list with major,minor,point integers. Having a single integer version is simpler and already specified in both CIP-68 and CIP-25, etc...

[Ryun1]

Thanks for the great write up here @rphair, I think versioning is clearly an important topic for the community and probably warrants a large discussion. I am happy to help work on a CIP-0001 PR and or a CPS for the versioning of CIPs.

[rphair]

Good to know @Ryun1 and I hope we are setting a precedent to be proactive and well-documented in each CIP about either an implementation of versioning or an agreed-upon explanation of why versioning won't be used... as in your latest #509 (comment)

[rphair]

@mmahut I brought up this issue at the CIP editors' meeting today and we agreed the top priority is to create a PR to update CIP-0068 with a new version accommodating the 444 RFT Standard introduced in #494.

In conversation with @KtorZ I volunteered to do the PR, but upon further research I don't think it's a simple matter of increasing a version number. How the version number is applied seems to involve some design decisions, as per these questions:

1 - Would the version number (an integer "serial number" making more sense than a semantic version) be increased from 1 to 2 for

• all the defined asset name labels (indicating that the 444 designation is now a possible choice for all metadatums from that point forward); or
• only the 444 asset name label (leaving the previously defined asset name labels unchanged: i.e. the new labels don't affect the old ones)?

In the latter case, it seems the document itself should also have a version number equal to the highest defined asset label version number, and therefore also a version history (table) indicating which CIP-0068 version corresponds to what list of supported asset name labels.

The choice here would indicate a paragraph to add to the specification, saying whether a new asset name label increments all the asset name label version numbers or just assigns the highest number so far to the label(s) added in the new version.

2 - If there is to be a (minimum) supported version number for each of these asset name labels (i.e. the second choice above), that suggests to me the best place to define a "minimum supported version" would be in the reference.json table of CIP-0067 rather than the text of CIP-0068, since presumably services like Blockfrost will need to make use of this table.

Therefore @mmahut please I think it is time for you to step in and let us know exactly what version definition would satisfy the problem you pointed out here:

Should the CIPs be in some way versioned? At Blockfrost, we claim to suppor CIP-68 but a totally new implementation has been added to it, making it incompatible for now.

because it will be too much trial & error for me to propose a versioning scheme for a system that I have no practical experience with... though if @KtorZ understands the requirement well enough then maybe I could do the updates based on his recommendations. (cc @AndrewWestberg)

[KtorZ]

I'll propose something @rphair, and continue the discussion from there. I am leaning towards an overarching version number that applies to the entire specification. As well as disclaimers associated with newly introduced or removed elements from new versions.

[rphair]

Recent comment about applying a version to the overall spec (i.e. the CIP document) as opposed to components of it (or no explicit versioning at all): #509 (comment)

... we regretted that CIP-30 did not have a version number for its spec to manage this change

[rphair]

I believe the CIP-0068 issue has been handled by #523, with the decision to version each of the asset name labels with respect to an overall version number. I didn't think of this before but an additional advantage of the way this is written is that it allows label support to be dropped in future versions (e.g. if a label was split).

Especially if there were lots more labels someday, we should still keep in mind the future option of defining the supported versions (min_version and max_version) in the CIP-0067 table rather than the CIP document text.

Please let's keep discussion on this issue going until we have the same kinds of matters resolved for some other CIPs. 🤓

edit (at closing time): changing language in first line to avoid GitHub extracting an inappropriate "May be fixed by" summary (if anything, this issue will eventually be fixed by #563)

[Crypto2099]

This is actually poignant to a discussion I was having this morning with @AndrewWestberg and per our discussion on the proposed Proof of Onboarding CIP (@rphair) where we discussed not making changes directly to a CIP (like CIP-13) but instead to introduce a new CIP that will add additional functionality to an existing CIP.

What we discussed in this context was actually more for the GitHub organizational purposes but it seems that if this will be the case moving forward we should add a CIP versioning syntax that will allow future/subsequent CIP extensions to be easily clustered and categorized underneath a parent structure in such a way as to enable to new developer to easily come into the ecosystem and find all relevant CIPs underneath a particular topic (like CIP-30).

For example, versioning and categorization could work by specifying the "parent" CIP number, followed by a sub-identifier, followed by an extension version integer such as:

• CIP-13 (parent)
  • Proof of Onboarding Spec (sub) (set to 1 for the sake of this example)
    • Version 1 (13.1.1)
    • Version 2 (13.1.2)

Using the above syntax we can see that it will be easy to "group" all Cardano URI specifications under a parent while keeping the individual PRs manageable and isolated to prevent overwriting and other chaos that comes from multiple authors modifying the source document directly.

[rphair]

@Crypto2099 now that there is a tangible PR for versioning requirements I think we will have to continue the discussion here: #563 ... I'll keep your last #520 (comment) in mind to see if there's any way these two goals are compatible (it may help for you to restate your comment there in terms of the proposed changes).

[rphair]

@Crypto2099 @AndrewWestberg in hindsight I should not have closed this since your last suggestion #520 (comment) is a more significant change than #563 or any changes to CIP-0001 that are likely to be universally agreed upon any time soon.

Therefore we should keep this open in the long term to accumulate & debate such suggestions. After the CIP-0068 matter was resolved early on with #523, the "thin" dev feedback we've had in this issue so far might simply have been because of the no-longer-appropriate title. So I'll give it a more general & meaningful one: hopefully that will attract more attention to your last suggestion & any other alternatives.

(edit) @Ryun1 I'll follow your lead from the CIP Discord and direct people to #563 for recommendations on immediate changes & definitions of "versioning" itself, while we can leave this open in the longer term to consider more radical alternatives to the usually slow evolution of CIP-0001.

[rphair]

This actually closed automatically (and I'm not really sure why GitHub did it) but I don't personally see a need to keep it open anymore, since the new versioning standards seem pretty well adopted by the whole community now. cc @Ryun1

[Ryun1]

We can always reopen, or open a new one when/if the problem arises again 😎