Clearly label the status of each specification version

[polina-c]

Created per @zeroasterisk 's request.

Work with team to come up with the proper labels for our versions and update the docs pages.

Initial suggestion:

• v0.8 = legacy
• v0.9 = current
• v0.10 = draft

[jacobsimionato]

There was a proposal (see chat thread) from @gspencergoog for this set of statuses for specifications:

• Draft: Under active development, not reviewed yet, not implemented in SDKs (currently v0.10)
• Candidate: In the process of being reviewed and implemented in one or more SDKs as a proof-of-concept. Changes are still possible but should be kept minor (this was v0.9 up until a month or so ago)
• Final: A finalized specification that will only be modified to correct ambiguities or errors. SDKs can and should implement it. (v0.8 and v0.9)

Re legacy: I don't think we should use a term like this at the specification level because it implies that everyone should be using the current version all the time, while really we want an ecosystem that can support multiple versions simultaneously.

Re SDK support: Let's have SDKs declare support for specification versions as a separate matter. E.g. each SDK can have a compatibility table etc.

[jacobsimionato]

WDYT about the above @polina-c and others?

BTW we have some mild language around specification status in the READMEs e.g. "This specification is closed." in https://github.com/google/A2UI/tree/main/specification/v0_9 and "This specification is currently under development." in https://github.com/google/A2UI/tree/main/specification/v0_10 .

[polina-c]

Thanks for the summary.

I agree that legacy is not the best label here. How about finalized?

The label candidate does not look right for me for v0.9.

v0.9 is what we recommend for new users, right? If we name it 'candidate` it will sound as if we do not recommend it yet.

How about allowing versions to have many labels:

• finalized - active development is finished here
• latest - recommended for new users
• pilot - ready for experiments, but not finalized
• draft - not ready for use yet
• deprecated - a version that is not recommended for use (it may be that we will never have such versions)

With application to what we have now:

• v0.8: finalized
• v0.9: finalized, latest
• v0.10: draft

Thoughts?

[jacobsimionato]

LGTM with two comments! Nit: slight preference for final vs finalized because it's a bit simpler.

Yes I agree with you re candidate not being appropriate for v0.9 right now - I meant previously it was the candidate. I think we should have a candidate status, because otherwise, when a version moves from draft to final, people inevitably find small issues when they're doing the first SDK implementations and need to fix them. If we leave it as draft, people want to make big changes that are disruptive, while if we make it final we have to break our own rules to allow small improvements which make sense practically.

[polina-c]

Sounds good: renamed pilot to candidate and finalized to final.

• final: active development is finished here
• latest: recommended for new users
• candidate: ready for experiments, but not finalized
• draft: not ready for use yet
• deprecated: a version that is not recommended for use (it may be that we will never have such versions)

With application to what we have now:

v0.8: final
v0.9: final, latest
v0.10: draft

[andrewkolos]

TL;DR: I agree with @polina-c and @jacobsimionato's discussion from minutes ago, though I'm not 100% on "latest" (feels more applicable to library releases, not specifications, and I'd still call v0.10 the "latest").

"Pilot" is not something I recognize in the context of software or standards--I've only heard it used in the context of rollout/ops (the first deployment in a progressive rollout) or media (a short production-grade run of something done before committing to bigger production).

"Draft," "Candidate," and "Final" are the terms I'm used to (sometimes there's an "In Review" or "Proposed" stage in there as well). However, I understand there's quite a bit of liminal space between those, which is why I'm guessing things like language specs have more than 3 stages (e.g. Python, JS TC39, and Java)¹.

Then again, language spec proposals are for individual refinements, not paradigm shifts; so I'm really comparing apples to oranges here 🤷.

Aside: Interestingly, to my limited knowledge, language specs usually roll on time schedules ("new big version every N months, whatever new thing/breaking change is ready will be introduced in that version.") I guess the only other example I'm familiar with is W3C with HTML, but IIRC they gave up altogether and HTML is just a living standard (i.e. there will be no HTML 6). CSS is the same. Then again, HTML and CSS are way more mature--incomparable to A2UI. For more examples, I'd look to the IETF, IEEE, ISO, etc.

Footnotes

1. Examples: https://tc39.es/process-document/, https://jcp.org/ja/jsr/stage, https://www.w3.org/Style/2011/CSS-process, https://peps.python.org/pep-0001/ (I think PEP also later got augmented with an additional "Provisional" stage as well) ↩

[polina-c]

You think latest is not the best term, right? It may be.

Do we need some label to show what version we recommend to new users?
Or we want them to search for final with biggest number themselves?

About other protocols: I checked them, all of them have their specific context and use cases, and there is no consistency.

[yjbanov]

Do we need a "latest"/"current" label? Can we have just two: final and draft? The latest is implied by the semver version number, no?