carbon-language · chandlerc · Jul 14, 2024 · Jul 2, 2024 · Jul 2, 2024 · Jul 3, 2024
diff --git a/docs/project/versioning.md b/docs/project/versioning.md
@@ -0,0 1,270 @@
 # Toolchain and language versioning
 
 <!--
 Part of the Carbon Language project, under the Apache License v2.0 with LLVM
 Exceptions. See /LICENSE for license information.
 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
 [Pull request](https://github.com/carbon-language/carbon-lang/pull/4105)
 
 <!-- toc -->
 
 ## Table of contents
 
 - [Overview](#overview)
 - [Major version increments](#major-version-increments)
  - [Breaking changes](#breaking-changes)
  - [Exclusions to what constitutes a breaking change](#exclusions-to-what-constitutes-a-breaking-change)
 - [Minor version increments](#minor-version-increments)
 - [Patch version increments](#patch-version-increments)
  - [Examples:](#examples)
 - [Pre-release versions](#pre-release-versions)
  - [Release qualification pre-releases: `MAJOR.MINOR.PATCH-rc.N`](#release-qualification-pre-releases-majorminorpatch-rcn)
  - [Incremental development versions: `MAJOR.MINOR.PATCH-0.{nightly,dev}.N`](#incremental-development-versions-majorminorpatch-0nightlydevn)
  - [Nightly pre-release versions](#nightly-pre-release-versions)
  - [Development pre-release versions](#development-pre-release-versions)
 - [Relevant proposal](#relevant-proposal)
 
 <!-- tocstop -->
 
 ## Overview
 
 Carbon uses a single versioning scheme across both the language itself and
 toolchain, including the standard library, compiler, linker, and all development
 tools released by the main Carbon project.
 
 The scheme conforms to and is closely based on Semantic Versioning
 (https://semver.org/ -- version 2.0.0):
 
 - Carbon versions: `MAJOR.MINOR.PATCH`
 - Releases with backwards incompatible changes, including a deprecation that
  might trigger a build-breaking warning, increment `MAJOR` after reaching the
  `1.0` milestone, and increment `MINOR` before then.
 - Releases with only backwards compatible changes are not expected to happen.
 - Releases containing only bug fixes increment `PATCH`.
 - Pre-release suffixes:
  - `MAJOR.MINOR.PATCH-rc.N`: The N-th potentially viable candidate for a
  release.
  - `MAJOR.MINOR.PATCH-0.nightly.YYYY.MM.DD`: A nightly incremental
  development build on a particular day during development of that
  version.
  - `MAJOR.MINOR.PATCH-0.dev`: An interactive, incremental development build
  on a particular day by some developer during development of that
  version.
 
 See the sections below for the details of each aspect of these versions.
 
 ## Major version increments
 
 Aligned with SemVer, the major version must increment for any _breaking change_
 to the language or any part of the toolchain.
 
 The first increment from 0 to 1 is expected to be based on achieving a desired
 milestone of feature completeness and quality to declare the language to have
 reached a stable version.
 
 Subsequent increments are expected to be done with a time-based release
 strategy. Features (or breaking changes) ready to ship will do so, and others
 will wait for the next major release. The exact cadence used is future work and
 should be determined based on discussions with Carbon's users in the ramp up to
 and after reaching the 1.0 milestone.
 
 However, just because we increment the major version for a major release and
 _can_ make breaking changes doesn't mean we _will_ or _should_. Breaking
 language changes are extraordinarily expensive for users due to the inherent
 scale of churn they impose. It is tempting to try to make non-breaking releases
 instead, but our experience with C language, compiler, and standard library
 updates is that truly making no breaking changes is extremely difficult and
 overly constraining. We expect most releases, especially in the early phases of
 the language to involve _some_ amount of breaking change and will simply work to
 make these as cheap to upgrade through and minimal as we can.
 
 At some future point, it is possible that Carbon will become so stable that it
 makes sense to consider using minor version increments for some releases. If and
 when this happens, we should revisit our versioning and release policies to
 establish a predictable and unsurprising structure.
 
 ### Breaking changes
 
 Beyond traditional breaking API changes in either standard library APIs or tool
 APIs, Carbon also includes breaking changes in the language or toolchain.
 Language and toolchain breaking changes are any that cause correct, functioning,
 and non-reflective code to become invalid, rejected, incorrect, or silently
 change behavior.
 
 ### Exclusions to what constitutes a breaking change
 
 Carbon excludes "reflective code" which is in some way detecting the Carbon
 version, or the presence or absence of features and as a consequence can be
 "broken" by detecting changes that are correctly designed to otherwise be
 non-breaking. We don't want adding features to be considered a breaking change
 and so exclude code that specifically detects such additions.
 
 Carbon also excludes breaking changes to incorrect code unless it was accepted
 and functioning in some useful, and typically widespread, way despite its bugs.
 
 ## Minor version increments
 
 Currently, Carbon plans to primarily use the minor version increments with a 0
 major version to track our progress towards our 1.0 milestone of a feature
 complete initial language. As a consequence we have defined 0.1 and 0.2
 milestones and may define more steps as needed.
 
 Beyond this and in a post-1.0 language world, we expect most significant
 features to also accompany some small and manageable breaking changes from
 deprecations. We may choose to revisit this in the future, but our current plan
 is not to make minor version releases post-1.0 and instead focus on our
 commitment to making those updates both easy and scalable for language users.
 
 ## Patch version increments
 
 The patch version will increment when the change is fundamentally a bug fix to a
 previously released version. We expect the vast majority of these to be strictly
 backwards compatible bug fixes.
 
 Patch releases are expected to be driven by demand, and not necessarily present
 if unnecessary. However, the exact schedule and process will be determined as
 part of getting ready for the 1.0 milestone. Before that milestone we don't
 commit to any particular process or cadence for patch releases as no release
 before that point should be considered stable.
 
 Note that we still consider restoring the _intended_ "public API" of a release
 to be a bug fix. When these bug fixes theoretically break new code in a way that
 would typically require a major version increment, they may be made with merely
 a patch version increment when they are in fact restoring our intended behavior
 for that release. However, we take the SemVer guarantees very seriously as these
 fixes can still be disruptive and so we work to hold a high bar for them:
 
 - They must be in some way fixing a _regressions_ for users from a previous
  release, not merely a missing feature.
  - Can even be a regression in the overall cohesion or reliability of the
  language or tools, which a bug in a new feature might erode.
  - Key is that we motivate any patch fix through the lens of a regression
  fix and stabilization rather than fixing forward.
 - The scope of disruption from the fix is demonstrably small, due to some
  combination of:
  - The short time duration of the release containing the regression.
  - The narrow scope of code constructs potentially impacted.
 - The impact of the regression is large and cannot be easily worked around,
  for example:
  - Undermining a core priority of the Carbon Language for a significant set
  of users.
  - Making the engineering cost of adopting the release uneconomical for any
  significant body of users.
 
 ### Examples:
 
 - We add a new feature that includes a bug which creates unsoundness and
  allows incorrect code to be compiled that will crash or exhibit UB when
  executed.
  - While this is a new feature and not a bug in an existing feature, it
  would be a _serious_ regression to the reliability of the language as a
  whole and the ability of users to reason about the correctness of
  programs.
  - This would be a good candidate for a patch release to address unless it
  is found very late (months) after the release _and_ the only ways to
  address would have similarly bad effects on code written since the
  initial release.
  - Even that level of user disruption could potentially be overcome if for
  example the bug led to security vulnerabilities.
 - We add a narrowly used new feature that includes a bug where some code
  patterns that _should_ work with the feature are rejected at compile time or
  crash reliably.
  - Unlikely this is worth a patch release to make an invasive change given
  the narrow use case.
  - A good candidate to introduce a warning or error on using the feature in
  the way that might lead to a crash, and possibly on using the feature at
  all.
 - We add a compiler opt-in feature behind a flag that doesn't work reliably.
  - Good candidate to have the flag disabled or trigger a warning message.
  - Not a good candidate to try to fix the feature forward.
 - We add a compiler opt-out feature that doesn't work reliably.
  - What to do likely depends on the scope of users impacted. If _very_ few
  users impacted, possibly just document how to opt-out.
  - If enough are impacted to be a nuisance and a regression in experience
  in general, likely worth attempting a patch release that narrowly fixes
  or mitigates the issue.
 
 ## Pre-release versions
 
 Beyond the major, minor, and patch versions of an actual release, SemVer
 provides a foundation for pre-release version management. However, it is a very
 open-ended foundation with a wide range of possibilities and no particular
 semantic model provided. Some of this is to support the wide variety of
 different needs across different projects. It also reflects the fundamentally
 less crisp and well defined criteria needed for pre-releases.
 
 That said, Carbon should try to have a small and well articulated scheme of
 pre-release versions to help communicate what these releases do and don't
 constitute and how they should be interpreted. These are selected to provide a
 framework that allows pre-release versions to order in a reasonably cohesive way
 when compared using SemVer.
 
 In descending order, Carbon pre-releases may use:
 
 - `MAJOR.MINOR.PATCH-rc.N`
 - `MAJOR.MINOR.PATCH-0.nightly.YYYY.MM.DD`
 - `MAJOR.MINOR.PATCH-0.dev`
 
 We expand on each of these below to provide criteria and details.
 
 ### Release qualification pre-releases: `MAJOR.MINOR.PATCH-rc.N`
 
 We create release candidate or "rc" pre-releases when we believe that version to
 be complete and ready to release and want to collect feedback. There should not
 be interesting or significant gaps, even known ones, from the intended release.
 The expectation should always be that unless some feedback arrives to the
 contrary, the release candidate could simply become the release.
 
 For each pre-release category, we always suffix with a sequential count `N` of
 the pre-releases at that version. We must start with a `.0` in order to have
 subsequent iterations of the same version and category of pre-release to sort
 after the first.
 
 ### Incremental development versions: `MAJOR.MINOR.PATCH-0.{nightly,dev}.N`
 
 These are versions that are not in any way associated with the actual expected
 release, but are periodically produced as an incremental tracking of development
 progress. Because they are not expected to be part of qualifying a specific
 release, they're not defined by any particular criteria of completeness or
 readiness. In practice, these will occur at every stage between one release and
 the next.
 
 #### Nightly pre-release versions
 
 These are automated incremental development versions built each night when the
 automated testing passes. There is _no_ attempt to provide any higher quality
 bar or refinement than whatever was in the tree at the time the automation runs,
 and whatever automated tests are present pass.
 
 It is important to emphasize that the primary use case of these pre-release
 versions is not to evaluate a potential release but for the developers and
 contributors to Carbon itself to track incremental development progress. That
 development-oriented goal drives how they are built and what they do and don't
 provide.
 
 Mechanically, we prefix the `nightly` pre-release version component with a `0`
 component to ensure these versions sort before any and all release qualification
 pre-release versions. We also add a date-derived suffix to provide a rough
 chronological ordering of nightly builds with otherwise identical versions.
 
 #### Development pre-release versions
 
 During development, interactive builds of Carbon need to be versioned in an
 unambiguous way, and we do that with the `dev` pre-release version. Much like
 nightly versions, these are only produced as artifacts of development activities
 and are never part of any actual release process. These versions are further not
 built expected to be automated or necessarily repeatable. They may contain
 in-flight edits and all manner of other variations.
 
 Mechanically, we prefix the `dev` pre-release version component with `0` in the
 same way as `nightly` is prefixed to ensure effective ordering. We don't add any
 additional information to keep the mechanics of development builds simple -- for
 example, there is no easy way to extract the date of the build. The exact
 timestamp of the build may be available but doesn't participate for simplicity
 and minimizing cache impact.
 
 ## Relevant proposal
 
 - [Proposal p4105](/proposals/p4105.md)