| # Release | |
| A Fuchsia _release_ is a set of generated artifacts that are the output of the | |
| Fuchsia project at a given point in time, published under a specific _release | |
| version_ name. Each Fuchsia release implements the ABI for a set of API levels | |
| and thus can run any component whose build-time target API level is in that set. | |
| Note: To learn more about the Fuchsia release process, see | |
| [Release process](#release-process). | |
| A release consists of: | |
| - The [Integrator Development Kit (IDK)][idk], a small set of libraries, | |
| packages, and tools required to build and run programs that target Fuchsia. | |
| - A small number of SDKs based on the IDK (for example, the [Bazel | |
| SDK][bazel-sdk]). | |
| - The Operating System (OS) binaries, including the kernel, bootloaders, | |
| packages, tools, and other ingredients necessary to configure and assemble | |
| Fuchsia [product bundles][product-bundle]. | |
| - A number of pre-assembled product bundles (for example, the [workbench] | |
| product)[^historical]. | |
| - Various other artifacts, such as documentation and [Compatibility Tests for | |
| Fuchsia (CTF)][ctf] builds. | |
| There's no single archive that contains all of these artifacts; different | |
| artifacts are produced by different builders and uploaded to different | |
| repositories. Some artifacts are freely available online, and some are | |
| confidential. Both the IDK and the OS binaries have both public and | |
| confidential variants. | |
| What unites them is that: | |
| - They are all built exclusively from a single revision of the Fuchsia [source | |
| tree][source-tree] (specifically, the Google-internal version of | |
| [`integration.git`][integration.git]), and | |
| - They are all published to their respective repositories under the same | |
| _release version_. | |
| [^historical]: Some of these products are defined in the Fuchsia source tree | |
| for purely historical reasons, and will be moved out-of-tree to promote | |
| separation between product and platform. | |
| ## Release versions {#release-versions} | |
| A _release version_ is a string of characters that names a release. | |
| Each release version has a corresponding tag in the Google-internal version of | |
| `integration.git`, which immutably points to the git commit from which the | |
| release binary artifacts were built. | |
| Versions are named `M.YYYYMMDD.R.C` (e.g. `2.20210213.2.5`) where: | |
| * `M` indicates the "[milestone](#milestone)" of the release. | |
| * `YYYYMMDD` is the date when the release's history diverged from the `main` | |
| branch. | |
| * `R` indicates the "release" version number. It starts at `0` and increments | |
| when multiple releases are created on the same date. | |
| * `C` indicates the "candidate" version number. It starts at `1` and increments | |
| when changes are made to a previous release on a _milestone release | |
| branch_. | |
| ## Release process {#release-process} | |
| Fuchsia has the following types of releases: | |
| * [Canary releases](#canary) | |
| * [Milestone releases](#milestone) | |
| ### Canary releases {#canary} | |
| A few times a day[^time-periods], a _canary_ release is created, based on the | |
| last-known-good revision of the Fuchsia source tree. Concretely, a git tag is | |
| applied to that revision in the Google-internal version of `integration.git`, | |
| and various builders are triggered to build and publish the artifacts described | |
| above. Canary releases do not get their own release branches, only tags. | |
| Each canary release is only supported for a brief window - until the next | |
| canary release. Bugfixes are not cherry-picked onto canary releases. (Put | |
| another way: the "candidate" version number of a canary release should always | |
| be "1".) If a bug is found in a canary release, a fix for that bug will be | |
| applied to the `main` branch of the Fuchsia source tree. Clients impacted by | |
| that bug should roll back to an earlier release and/or await a subsequent | |
| canary release that includes the fix. | |
| As such, canary releases are appropriate for development and testing, but are | |
| not recommend for production. For production use cases, _milestone | |
| releases_ are recommended. | |
| [^time-periods]: This document does not specify any particular release cadence. | |
| Time periods are named to provide an "order of magnitude" estimate for the | |
| frequency of various processes. Cadences will change as project and | |
| customer needs evolve. | |
| ### Milestone releases {#milestone} | |
| Every few weeks, a _milestone release branch_ is created in both the | |
| Google-internal version _and_ the public mirror of `integration.git`, starting | |
| from the git commit for an existing "known good" canary release. Releases | |
| originating from a milestone release branch are known as _milestone releases_ | |
| or _stable numerical releases_. | |
| Milestones are numerically sequential, and often prefixed with an "F" when | |
| discussed (as in, "the F12 release branch"). | |
| Once the F`N` milestone release branch has been cut, mainline development in | |
| the Fuchsia source tree will continue on the `main` branch, working towards the | |
| next F`N+1` release, and canary releases will have a version beginning with | |
| `N+1`, as shown in the following diagram: | |
|  | |
| Note: For more information on release versions, see | |
| [Release versions][release-versions]. | |
| Milestone releases share the `M.YYYYMMDD.R` part of their version with the | |
| canary release on which they are based, and therefore only the "candidate" | |
| version number `C` changes between releases built from a given milestone | |
| release branch. Note that this means it's not always immediately obvious from a | |
| version whether that release is a canary or milestone release (though a value | |
| of `C` greater than 1 indicates that a release comes from a milestone release | |
| branch). | |
| Unlike canary releases, milestone releases are _supported_ for some number of | |
| weeks after their creation. That is, improvements may be made to milestone | |
| release branches after the release branch is cut. After each change to a | |
| milestone release branch, a new milestone release will be published with a | |
| larger "candidate" version number. | |
| ## Development on `main` {#development-on-main} | |
| As a matter of general policy: | |
| * Features are developed on `main`, not in milestone release branches. | |
| * Changes made to milestone release branches land on `main` first, and then are | |
| cherry-picked onto the branch. | |
| * Only changes that fix bugs (be they related to quality, security, privacy, | |
| compliance, etc) will be made to milestone release branches. We do not make | |
| changes that introduce new functionality to milestone release branches. | |
| These policies are designed to minimize the odds that changes to milestone | |
| release branches introduce new bugs, and thus the reliability and stability of | |
| releases associated with a given milestone should improve over time. As such, | |
| downstream customers are encouraged to eagerly adopt these new milestone | |
| releases. | |
| Under certain exceptional circumstances, we may need to stray from these | |
| policies (e.g., a security fix may need to be developed on a confidential | |
| branch to avoid publicizing a vulnerability before a fix is ready). Whether to | |
| include a change on a milestone release branch is ultimately the release | |
| manager's decision. | |
| [integration.git]: https://fuchsia.googlesource.com/integration/ | |
| [source-tree]: /docs/get-started/learn/build/source-tree.md | |
| [ctf]: /docs/development/testing/ctf/overview.md | |
| [workbench]: /docs/contribute/governance/rfcs/0220_the_future_of_in_tree_products.md | |
| [product-bundle]: /docs/glossary#product-bundle | |
| [idk]: /docs/development/idk/README.md | |
| [bazel-sdk]: /docs/development/sdk/index.md | |
| [RFC-0227]: /docs/contribute/governance/rfcs/0227_fuchsia_release_process.md | |
| [release-versions]: #release-versions |