ABPSC 3.4b1 NO IDEA Avatar
  1. OMG Issue

ABPSC — Adopt semantic versioning for specifications, including during development

  • Key: ABPSC-72
  • Status: open  
  • Source: Object Management Group ( Dr. Jason McC. Smith)
  • Summary:

    The P&P is rife with legacy terminology, but one of the more confusing bits is the use of the word 'beta' for the production of specifications.

    In software development and in industry, 'semantic versioning' is a well understood de facto standard. It provides a well-formed and consistent format for conveying compatibility with prior versions of a product while clearly communicating lineage on a timeline.

    The SemVer project documents this format with copious explanation, and is the most commonly used semantic version specifcation: https://semver.org

    This highlights some of the current problems.

    1. 'Alpha' and 'beta' have specific meanings in industry: an alpha version is incomplete and still being developed, while beta is used to indicate a product that has nominally finished its internal development, and is ready for public testing and feedback. This does not match the P&P definitions or guidance text in Sec 4.4.2, where Alpha is a document not yet worked on by an FTF, and Beta is an incomplete document during FTF and RTF, but Beta 1, Beta 2, etc are only products described in reference to an FTF, not an RTF.

    2. There is disagreement on what the version of a Submission is (if any!) during the TC and BoD Adoption votes before it reaches its first FTF. (Section 4.1.2)

    3. There is a broad misunderstanding that there are only Beta 1 and Beta 2 documents, which not only exposes a conflict within the P&P but is also not in line with industry norms. (See ABPSC-70 / ABPSC-71 for an example of a need for specific clarification on this point just to make sure a subgroup is following the P&P for a specification approaching the end of an FTF.)

    Historically, the intent of the process currently documented in the P&P is close to current convention, but it is sufficiently out of step that it causes confusion.

    Proposal: Adopt the SemVer standard for our versioning, throughout our process.

    This complements the process in the P&P and would provide opportunities for clarification.

    Any document that is being worked on by a TF, FTF or RTF that is not yet ready for public review is an Alpha. There can be any number of Alpha documents during a development, finalization or revision process. (This is a refinement of the Alpha Specification definition in the P&P.)

    Any non-completed document that is available for public review and comment is a Beta. There can be any number of Beta documents produced during a review phase. (This is a refinement of the Beta Specification definition in the P&P.)

    Any document that is being recommended for adoption (i.e. passing AB review, TC voting, BoD voting) is a Final Candidate. There can be any number of FC documents, but revisions will cause a restart of the recommendation process. (This is a new class of document not defined in the P&P.)

    Any document that is formally adopted by the OMG as a final version of a specification will be a simple SemVer compliant x.y.z version. (This is a refinement of the Formal Specification definition in the P&P.)

    A concrete example needs to be worked through in the Comments below.

    This would greatly clarify where in the process a document is by quickly looking at the version, and also match widely adopted and understood versioning protocols. Unfortunately it would require a rather pervasive change to the P&P, but referring to SemVer 2.0 as the base would greatly simplify the language in the P&P and allow the specifics of the process to be more clearly communicated.

  • Reported: ABPSC 3.3 — Fri, 13 Sep 2024 15:00 GMT
  • Updated: Sun, 17 Nov 2024 00:11 GMT