@@ -4,61 +4,229 @@ icon: octicons/package-16
44
55# Release management
66
7+ ## :octicons-book-16: Overview
8+
9+ Releases are the process by which we build and deliver software to our users.
10+ We use a mix of automation and operational practices as part of our continuous
11+ delivery (CD) efforts.
12+
13+ Releases have the following goals (among others):
14+
15+ * Produce and publish easily installable packages to common package managers
16+ for users.
17+ * Introduce checkpoints with predictable versions around which release notes,
18+ testing efforts, and other related activities can align.
19+ * Improve project and ecosystem velocity and stability.
20+
21+ ### :octicons-calendar-16: Stable and nightly releases
22+
23+ In addition to stable releases, we build and publish nightly releases too.
24+ Nightly releases are less tested and may not include all configurations at all
25+ times, but they are convenient to install as a preview for what the next stable
26+ release will contain.
27+
28+ ![ IREE Architecture] ( ../../assets/images/releases_source_to_stable_dark.svg#gh-dark-mode-only )
29+ ![ IREE Architecture] ( ../../assets/images/releases_source_to_stable.svg#gh-light-mode-only )
30+
31+ * Stable releases are published to GitHub releases, are pushed to PyPI, and are
32+ installable via ` pip install ` using default options.
33+ * Nightly releases are published to only GitHub releases as "pre-releases" and
34+ are installable via ` pip install ` using non-default options like
35+ [ ` --find-links ` ] ( https://pip.pypa.io/en/stable/cli/pip_install/#finding-packages )
36+ and our hosted index page at < https://iree.dev/pip-release-links.html > .
37+
38+ ### :material-graph-outline: Projects in scope
39+
40+ The IREE release process currently considers packages in these projects to be
41+ in scope:
42+
43+ * [ iree-org/iree] ( https://github.com/iree-org/iree )
44+ * [ iree-org/iree-turbine] ( https://github.com/iree-org/iree-turbine )
45+ * [ nod-ai/shark-ai] ( https://github.com/nod-ai/shark-ai )
46+
47+ !!! info
48+
49+ If you maintain a project that you would like to connect with this release
50+ process, please reach out on one of our
51+ [communication channels](../../index.md#communication-channels). The current
52+ project list is driven by the priorities of the core project maintainers and
53+ we would be happy to adapt the process to include other projects too.
54+
55+ The dependency graph looks like this:
56+
57+ ``` mermaid
58+ graph TD
59+ accTitle: Dependency graph between in-scope packages
60+
61+ subgraph iree["iree-org/iree"]
62+ iree-base-compiler
63+ iree-base-runtime
64+ iree-tools-tf
65+ iree-tools-tflite
66+ end
67+
68+ subgraph turbine["iree-org/iree-turbine"]
69+ iree-turbine
70+ end
71+
72+ iree-base-compiler --> iree-turbine
73+ iree-base-runtime --> iree-turbine
74+
75+ subgraph sharkai["nod-ai/shark-ai"]
76+ sharktank
77+ shortfin
78+ shark-ai
79+ end
80+
81+ iree-base-compiler --> sharktank
82+ iree-turbine --> sharktank
83+ iree-base-runtime -. source dependency .-> shortfin
84+ sharktank --> shark-ai
85+ shortfin --> shark-ai
86+ ```
87+
88+ #### :fontawesome-solid-circle-nodes: Types of dependency links
89+
90+ Most dependencies are loose requirements, not imposing strict limitations on
91+ the versions installed. This allows users to freely install similar versions of
92+ each package without risking issues during pip dependency resolution. This is
93+ important for libraries near the root or middle of a dependency graph.
94+
95+ ``` text title="iree-turbine METADATA snippet" hl_lines="2-3"
96+ Requires-Dist: numpy
97+ Requires-Dist: iree-base-compiler
98+ Requires-Dist: iree-base-runtime
99+ Requires-Dist: Jinja2>=3.1.3
100+ Requires-Dist: ml_dtypes>=0.5.0
101+ ```
102+
103+ The shark-ai package is special in that it is a leaf project acting as a full
104+ solution for ML model development that _ does_ specify precise versions. By
105+ installing this package, users will receive packages that have been more
106+ rigorously tested together:
107+
108+ ``` text title="shark-ai METADATA snippet"
109+ Requires-Dist: iree-base-compiler==3.2.*
110+ Requires-Dist: iree-base-runtime==3.2.*
111+ Requires-Dist: iree-turbine==3.2.*
112+ Requires-Dist: sharktank==3.2.0
113+ Requires-Dist: shortfin==3.2.0
114+ ```
115+
116+ This feeds back into the release process - while release candidate selection
117+ typically flows from the base projects outwards, leaf projects are responsible
118+ for testing regularly and ensuring that the entire collective continues to work
119+ as expected.
120+
121+ ### :octicons-calendar-16: Release timeline
122+
123+ Over the course of a release cycle there are several milestones to look out for:
124+
125+ * Week 0
126+ * Release ` X.Y.0 ` is published (see also
127+ [ Versioning scheme] ( ./versioning-scheme.md ) )
128+ * Versions in source code are updated to ` X.{Y+1}.0 ` (see also
129+ [ Creating a patch release] ( #creating-a-patch-release ) )
130+ * The next release date target is set for ~ 6 weeks later
131+ * Subprojects set goals for the release
132+ * ~ 1 week before the release date
133+ * Any unstable build/test/release workflows must be stabilized
134+ * Calls for release note contributions are sent out
135+ * Release notes are drafted
136+ * Release candidates are selected
137+ * Release candidates are tested
138+ * Release day
139+ * Release candidates are promoted, release notes are published
140+ * The cycle repeats
141+
142+ Downstream projects are encouraged to test as close to HEAD as possible leading
143+ up to each release, so there are multiple high quality candidates to choose from
144+ and release candidate testing processes require minimal manual effort.
145+
146+ !!! Note
147+
148+ We do not yet have a process for creating release branches. Instead, we
149+ choose a release candidate from nightly builds of the `main` branch. We
150+ also do not choose a cutoff point in advance for the release candidate
151+ selection.
152+
153+ This process will likely need to evolve for future releases.
154+
155+ ## :material-list-status: Release status
156+
157+ Stable release history:
158+ < https://github.com/iree-org/iree/releases?q=prerelease%3Afalse > .
159+
160+ ### iree-org projects
161+
162+ | Project | Package | Release status |
163+ | -- | -- | -- |
164+ | [ iree-org/iree] ( https://github.com/iree-org/iree ) | GitHub release (stable) | [ ![ GitHub Release] ( https://img.shields.io/github/v/release/iree-org/iree )] ( https://github.com/iree-org/iree/releases/latest ) |
165+ | | GitHub release (nightly) | [ ![ GitHub Release] ( https://img.shields.io/github/v/release/iree-org/iree?include_prereleases )] ( https://github.com/iree-org/iree/releases ) |
166+ | | ` iree-base-compiler ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-base-compiler.svg )] ( https://pypi.org/project/iree-base-compiler ) |
167+ | | ` iree-base-runtime ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-base-runtime.svg )] ( https://pypi.org/project/iree-base-runtime ) |
168+ | | ` iree-tools-tf ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-tools-tf.svg )] ( https://pypi.org/project/iree-tools-tf ) |
169+ | | ` iree-tools-tflite ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-tools-tflite.svg )] ( https://pypi.org/project/iree-tools-tflite ) |
170+ | [ iree-org/iree-turbine] ( https://github.com/iree-org/iree-turbine ) | GitHub release (stable) | [ ![ GitHub Release] ( https://img.shields.io/github/v/release/iree-org/iree-turbine )] ( https://github.com/iree-org/iree-turbine/releases/latest ) |
171+ | | ` iree-turbine ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-turbine.svg )] ( https://pypi.org/project/iree-turbine ) |
172+
173+ ### Community projects
174+
175+ | Project | Package | Release status |
176+ | -- | -- | -- |
177+ | [ nod-ai/shark-ai] ( https://github.com/nod-ai/shark-ai ) | GitHub release (stable) | [ ![ GitHub Release] ( https://img.shields.io/github/v/release/nod-ai/shark-ai )] ( https://github.com/nod-ai/shark-ai/releases/latest ) |
178+ | | ` shark-ai ` | [ ![ PyPI version] ( https://badge.fury.io/py/shark-ai.svg )] ( https://pypi.org/project/shark-ai ) |
179+ | | ` sharktank ` | [ ![ PyPI version] ( https://badge.fury.io/py/sharktank.svg )] ( https://pypi.org/project/sharktank ) |
180+ | | ` shortfin ` | [ ![ PyPI version] ( https://badge.fury.io/py/shortfin.svg )] ( https://pypi.org/project/shortfin ) |
181+
182+ ### Deprecated packages
183+
184+ | Project | Package | Release status | Notes |
185+ | -- | -- | -- | -- |
186+ | [ iree-org/iree] ( https://github.com/iree-org/iree ) | ` iree-compiler ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-compiler.svg )] ( https://pypi.org/project/iree-compiler ) | Renamed to ` iree-base-compiler `
187+ | | ` iree-runtime ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-runtime.svg )] ( https://pypi.org/project/iree-runtime ) | Renamed to ` iree-base-runtime `
188+ | | ` iree-runtime-instrumented ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-runtime-instrumented.svg )] ( https://pypi.org/project/iree-runtime-instrumented ) | Merged into ` iree[-base]-runtime `
189+ | | ` iree-tools-xla ` | [ ![ PyPI version] ( https://badge.fury.io/py/iree-tools-xla.svg )] ( https://pypi.org/project/iree-tools-xla ) | Merged into ` iree-tools-tf `
190+ | [ nod-ai/SHARK-Turbine] ( https://github.com/nod-ai/SHARK-Turbine ) | ` shark-turbine ` | [ ![ PyPI version] ( https://badge.fury.io/py/shark-turbine.svg )] ( https://pypi.org/project/shark-turbine ) | Renamed to ` iree-turbine `
191+
192+ ## :material-hammer-wrench: Release mechanics
193+
7194IREE cuts automated releases via a workflow that is
8195[ triggered daily] ( https://github.com/iree-org/iree/blob/main/.github/workflows/schedule_candidate_release.yml ) .
9196The only constraint placed on the commit that is released is that it has
10197[ passed certain CI checks] ( https://github.com/iree-org/iree/blob/main/build_tools/scripts/get_latest_green.sh ) .
11198These are published on GitHub with the "pre-release" status. For debugging this
12199process, see the [ Release debugging playbook] ( ../debugging/releases.md ) .
13200
14- We periodically promote one of these candidates to a "stable" release by
15- removing the "pre-release" status. This makes it show up as a "latest" release
16- on GitHub. We also push the Python packages for this release to PyPI.
17-
18- All stable (non-prerelease) releases can be viewed at
19- < https://github.com/iree-org/iree/releases?q=prerelease%3Afalse > .
20-
21- ## Release status
201+ We periodically promote one of these candidates to a "stable" release.
22202
23- | Package | Release status |
24- | -- | -- |
25- GitHub release (stable) | [ ![ GitHub Release] ( https://img.shields.io/github/v/release/iree-org/iree )] ( https://github.com/iree-org/iree/releases/latest )
26- GitHub release (nightly) | [ ![ GitHub Release] ( https://img.shields.io/github/v/release/iree-org/iree?include_prereleases )] ( https://github.com/iree-org/iree/releases )
27- Python iree-base-compiler | [ ![ PyPI version] ( https://badge.fury.io/py/iree-base-compiler.svg )] ( https://badge.fury.io/py/iree-base-compiler )
28- Python iree-base-runtime | [ ![ PyPI version] ( https://badge.fury.io/py/iree-base-runtime.svg )] ( https://badge.fury.io/py/iree-base-runtime )
29- Python iree-compiler (deprecated) | [ ![ PyPI version] ( https://badge.fury.io/py/iree-compiler.svg )] ( https://badge.fury.io/py/iree-compiler )
30- Python iree-runtime (deprecated) | [ ![ PyPI version] ( https://badge.fury.io/py/iree-runtime.svg )] ( https://badge.fury.io/py/iree-runtime )
31-
32- ## Running a release
203+ ## :octicons-rocket-16: Running a release
33204
34205A pinned issue tracking the next release should be filed like
35206< https://github.com/iree-org/iree/issues/18380 > . Developers authoring patches
36207that include major or breaking changes should coordinate merge timing and
37208contribute release notes on those issues.
38209
39- ### Picking a candidate to promote
210+ ### :material-check-all: Picking a candidate to promote
40211
41212After approximately one month since the previous release, a new release should
42213be promoted from nightly release candidates.
43214
44215When selecting a candidate we aim to meet the following criteria:
45216
46- 1 . ⪆4 days old so that problems with it may have been spotted
47- 2 . Contains no P0 regressions vs the previous stable release
48- 3 . LLVM submodule commit ideally exists upstream (no cherry picks or patches)
49- 4 . Includes packages for all platforms, including macOS and Windows
217+ 1 . Includes packages for all platforms, including macOS and Windows
218+ 2 . ⪆2 days old so that problems with it may have been spotted
219+ 3 . Contains no major regressions vs the previous stable release
50220
51221When you've identified a potential candidate, comment on the tracking issue with
52222the proposal and solicit feedback. People may point out known regressions or
53223request that some feature make the cut.
54224
55- ### Promoting a candidate to stable
225+ ### :octicons-package-dependents-16: Promoting a candidate to stable
56226
572271 . (Authorized users only) Push to PyPI using
58228 [ pypi_deploy.sh] ( https://github.com/iree-org/iree/blob/main//build_tools/python_deploy/pypi_deploy.sh )
59229
60- * For Googlers, the password is stored at < http://go/iree-pypi-password >
61-
622302 . Create a new release on GitHub:
63231
64232 * Set the tag to be created and select a target commit. For example, if the
@@ -94,15 +262,17 @@ request that some feature make the cut.
942623. Complete any remaining checkbox items on the release tracking issue then
95263 close it and open a new one for the next release.
96264
97- # # Creating a patch release
265+ # # :octicons-stack-16: Creating a patch release
98266
992671. Create a new branch.
100268
101269 Checkout the corresponding stable release and create a branch for the patch release:
102270
271+ < ! -- TODO(scotttodd): Does this need a branch, or would just a tag work? -->
272+
103273 ` ` ` shell
104- git checkout iree-3 .0.0
105- git checkout -b iree-3 .0.1
274+ git checkout v3 .0.0
275+ git checkout -b v3 .0.1
106276 ` ` `
107277
1082782. Apply and commit the patches.
@@ -127,3 +297,16 @@ request that some feature make the cut.
127297
1282986. Follow the documentation above to promote to stable.
129299 The step to create a new tag can be skipped.
300+
301+ # # :octicons-cross-reference-16: Useful references
302+
303+ * [Chapter 24: Continuous Delivery](https://abseil.io/resources/swe-book/html/ch24.html)
304+ in the
305+ [_Software Engineering at Google_ Book](https://abseil.io/resources/swe-book)
306+ * [Chapter 8: Release Engineering](https://sre.google/sre-book/release-engineering/)
307+ in the
308+ [_Site Reliability Engineering at Google_ Book](https://sre.google/sre-book/table-of-contents/)
309+ * [RELEASE.md](https://github.com/pytorch/pytorch/blob/main/RELEASE.md) in the
310+ [PyTorch repository](https://github.com/pytorch/pytorch)
311+ * [ONNX Releases](https://onnx.ai/onnx/repo-docs/OnnxReleases.html) for the
312+ [ONNX project](https://github.com/onnx/onnx)
0 commit comments