docs/about: propose OS platform/arch support tiers
PATCH 1/1 docs/about: propose OS platform/arch support tiers
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
---
This came out of the discussion about recent unnoticed breakage in NetBSD builds and what maintainers are expected todo about it (if anything)
https://lists.nongnu.org/archive/html/qemu-devel/2026-01/msg02543.html
docs/about/build-platforms.rst | 152 +++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+)
docs/about/build-platforms.rst +152 -0
@@ -171,3 +171,155 @@ Only 64-bit Windows is supported. .. _MacPorts: https://www.macports.org/ .. _MSYS2: https://www.msys2.org/ .. _Repology: https://repology.org/ + +OS Support Tiers +---------------- + +While the QEMU code targets a number of different OS platforms, they don't +all get the same level of support from the project. This applies to +contributor & maintainer expectations, CI automation and requirements +for merge gating. + +Tier 1 +~~~~~~ + +These platforms attain the highest level of quality offered by +the QEMU project. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs all available tests frameworks (unit, qtest, iotests, functional) + in CI + + * Merging code is gated on successful CI jobs + +This covers + + * Linux (x86_64, aarch64, s390x) + +Responsibilities: + + * Contributors MUST test submitted patches on one of Tier 1 platforms. + + * Contributors SHOULD test submitted patches on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST request contributors to fix problems with Tier 1 + platforms. + + * Maintainers MUST test pull requests on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge immediately. + + +Tier 2 +~~~~~~ + +These platforms are considered to be near Tier 1 level, but are +lacking sufficient automated CI testing cover to guarantee this. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs some test frameworks in CI + +This covers + + * Linux (mips64el, ppc64el, riscv64) + + * FreeBSD (x86_64) + + * macOS (aarch64) + + * Windows (x86_64) + +Responsibilities: + + * Contributors MAY test patches on Tier 2 platforms + by running a GitLab CI pipeline in their fork + + * Maintainers SHOULD request contributors to fix problems with Tier 2 + platforms. + + * Maintainers MUST test pull requests on all Tier 2 platforms, + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge quickly. + + +Tier 3 +~~~~~~ + +These platforms have theoretical support in the code, but have +little, or no, automated build and test coverage. Downstream +consumers (users or distributors) who care about these platforms +are requested to perform manual testing, report bugs and provide +patches. + + * Builds and tests may be broken at any time in Git HEAD and + releases + + * Builds are not integrated into CI + + * Tests are not integrated into CI + + * Merging code is not gated + +This covers: + + * NetBSD + * OpenBSD + * macOS (except aarch64) + * FreeBSD (except x86_64) + * Windows (except x86_64) + * Solaris + +Responsibilities: + + * Contributors MAY test patches on Tier 3 platforms manually + + * Maintainers MAY request contributors to fix problems + on Tier 3 platforms + + * Maintainers MAY test patches on Tier 3 platforms manually + + * Maintainers SHOULD NOT accept patches that remove code + targetting Tier 3 platforms even if currently broken + + * Downstream vendors SHOULD test RC releases on Tier 3 platforms + and provide bug reports and patches to address problems + +Note: if a Tier 3 platform is found to be significantly broken, +no patches are contributed for a prolonged period, and there is +no sign of downstream usage, it is liable to be moved to +"Unclassified" and thus be subject to removal. + + +Unclassified +~~~~~~~~~~~~ + +These platforms are not intended to be supported in the code +and outside the scope of any support tiers. + + * Code supporting these platforms can removed at any time + * Bugs reports related to these platforms will generally + be ignored + +This covers: + + * All 32-bit architectures on any OS + * Any OS not listed above + +Responsibilities: + + * Maintainers MAY decline patches that add code targetting + unclassified platforms + + * Maintainers MAY accept patches that remove code targetting + unclassified platforms
Signature · 1 line
2.52.0
Quoted 152 lines · Daniel P. Berrangé
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
Signed-off-by Daniel P. Berrangé <[email protected]>---
This came out of the discussion about recent unnoticed breakage in NetBSD builds and what maintainers are expected todo about it (if anything)
https://lists.nongnu.org/archive/html/qemu-devel/2026-01/msg02543.html
docs/about/build-platforms.rst| 152 +++++++++++++++++++++++++++++++++1 file changed, 152 insertions(+)docs/about/build-platforms.rst +0
-0@@ -171,3 +171,155 @@ Only 64-bit Windows is supported...
_MacPorts: https://www.macports.org/
.._MSYS2: https://www.msys2.org/
.._Repology: https://repology.org/docs/about/build-platforms.rst +110
-0+ +OS Support Tiers +---------------- + +While the QEMU code targets a number of different OS platforms, they don't +all get the same level of support from the project. This applies to +contributor & maintainer expectations, CI automation and requirements +for merge gating. + +Tier 1 +~~~~~~ + +These platforms attain the highest level of quality offered by +the QEMU project. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs all available tests frameworks (unit, qtest, iotests, functional) + in CI + + * Merging code is gated on successful CI jobs + +This covers + + * Linux (x86_64, aarch64, s390x) + +Responsibilities: + + * Contributors MUST test submitted patches on one of Tier 1 platforms. + + * Contributors SHOULD test submitted patches on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST request contributors to fix problems with Tier 1 + platforms. + + * Maintainers MUST test pull requests on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge immediately. + + +Tier 2 +~~~~~~ + +These platforms are considered to be near Tier 1 level, but are +lacking sufficient automated CI testing cover to guarantee this. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs some test frameworks in CI + +This covers + + * Linux (mips64el, ppc64el, riscv64) + + * FreeBSD (x86_64) + + * macOS (aarch64) + + * Windows (x86_64) + +Responsibilities: + + * Contributors MAY test patches on Tier 2 platforms + by running a GitLab CI pipeline in their fork + + * Maintainers SHOULD request contributors to fix problems with Tier 2 + platforms. + + * Maintainers MUST test pull requests on all Tier 2 platforms, + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge quickly. + + +Tier 3 +~~~~~~ + +These platforms have theoretical support in the code, but have +little, or no, automated build and test coverage. Downstream +consumers (users or distributors) who care about these platforms +are requested to perform manual testing, report bugs and provide +patches. + + * Builds and tests may be broken at any time in Git HEAD and + releases + + * Builds are not integrated into CI + + * Tests are not integrated into CI + + * Merging code is not gated + +This covers: + + * NetBSD + * OpenBSD + * macOS (except aarch64) + * FreeBSD (except x86_64) + * Windows (except x86_64) + * Solaris + +Responsibilities:
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 293
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+ + * Contributors MAY test patches on Tier 3 platforms manually + + * Maintainers MAY request contributors to fix problems + on Tier 3 platforms + + * Maintainers MAY test patches on Tier 3 platforms manually + + * Maintainers SHOULD NOT accept patches that remove code + targetting Tier 3 platforms even if currently broken
If an OS stops supporting a platform in new versions then due to the policy of supporting only the last two OS versions in QEMU may lead to breaking this. Maybe it tries to say that Tier 3 is intended to be fixed but no guarantees on when? It is also clarified below so maybe this clause is not needed or need to be reworded?
Quoted 6 lines
+ * Downstream vendors SHOULD test RC releases on Tier 3 platforms
docs/about/build-platforms.rst +5
-0+ and provide bug reports and patches to address problems + +Note: if a Tier 3 platform is found to be significantly broken, +no patches are contributed for a prolonged period, and there is +no sign of downstream usage, it is liable to be moved to
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 310
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+"Unclassified" and thus be subject to removal. + + +Unclassified +~~~~~~~~~~~~ + +These platforms are not intended to be supported in the code +and outside the scope of any support tiers. + + * Code supporting these platforms can removed at any time
can be removed
Quoted 5 lines
docs/about/build-platforms.rst +5
-0+ * Bugs reports related to these platforms will generally + be ignored + +This covers: +
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 325
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+ * All 32-bit architectures on any OS + * Any OS not listed above + +Responsibilities: + + * Maintainers MAY decline patches that add code targetting + unclassified platforms + + * Maintainers MAY accept patches that remove code targetting + unclassified platforms
Regards,
BALATON Zoltan
Quoted 77 lines · BALATON Zoltan
Quoted 76 lines · Daniel P. Berrangé
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
Signed-off-by Daniel P. Berrangé <[email protected]>---
This came out of the discussion about recent unnoticed breakage in NetBSD builds and what maintainers are expected todo about it (if anything)
https://lists.nongnu.org/archive/html/qemu-devel/2026-01/msg02543.html
docs/about/build-platforms.rst| 152 +++++++++++++++++++++++++++++++++1 file changed, 152 insertions(+)docs/about/build-platforms.rst +36
-0+Tier 3 +~~~~~~ + +These platforms have theoretical support in the code, but have +little, or no, automated build and test coverage. Downstream +consumers (users or distributors) who care about these platforms +are requested to perform manual testing, report bugs and provide +patches. + + * Builds and tests may be broken at any time in Git HEAD and + releases + + * Builds are not integrated into CI + + * Tests are not integrated into CI + + * Merging code is not gated + +This covers: + + * NetBSD + * OpenBSD + * macOS (except aarch64) + * FreeBSD (except x86_64) + * Windows (except x86_64) + * Solaris + +Responsibilities: + + * Contributors MAY test patches on Tier 3 platforms manually + + * Maintainers MAY request contributors to fix problems + on Tier 3 platforms + + * Maintainers MAY test patches on Tier 3 platforms manually +
Quoted 8 lines
Quoted 2 lines
+ * Maintainers SHOULD NOT accept patches that remove code
+ targetting Tier 3 platforms even if currently brokenIf an OS stops supporting a platform in new versions then due to the policy of supporting only the last two OS versions in QEMU may lead to breaking this. Maybe it tries to say that Tier 3 is intended to be fixed but no guarantees on when? It is also clarified below so maybe this clause is not needed or need to be reworded?
The policy on only supporting the most recent 2 releases of an OS applies universally regardless of the Tier levels. I should state that explicitly in this new doc to make that clear.
IOW, maintainers are free to remove code that is only relevant to OS versions /older/ than 2 releases whether that code is broken or not.
Quoted 20 lines
Quoted 7 lines
+ * Downstream vendors SHOULD test RC releases on Tier 3 platforms
docs/about/build-platforms.rst +5
-0+ and provide bug reports and patches to address problems + +Note: if a Tier 3 platform is found to be significantly broken, +no patches are contributed for a prolonged period, and there is +no sign of downstream usage, it is liable to be moved todocs/about/build-platforms.rst Only 64-bit Windows is supported. · line 310
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+"Unclassified" and thus be subject to removal. + + +Unclassified +~~~~~~~~~~~~ + +These platforms are not intended to be supported in the code +and outside the scope of any support tiers. + + * Code supporting these platforms can removed at any timecan be removed
Quoted 15 lines
Quoted 5 lines
docs/about/build-platforms.rst +5
-0+ * Bugs reports related to these platforms will generally + be ignored + +This covers: +docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 325
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+ * All 32-bit architectures on any OS + * Any OS not listed above + +Responsibilities: + + * Maintainers MAY decline patches that add code targetting + unclassified platforms + + * Maintainers MAY accept patches that remove code targetting + unclassified platforms
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
Quoted 184 lines · Daniel P. Berrangé
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
Signed-off-by Daniel P. Berrangé <[email protected]>---
This came out of the discussion about recent unnoticed breakage in NetBSD builds and what maintainers are expected todo about it (if anything)
https://lists.nongnu.org/archive/html/qemu-devel/2026-01/msg02543.htmldocs/about/build-platforms.rst | 152 +++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+)docs/about/build-platforms.rst +142
-0@@ -171,3 +171,155 @@ Only 64-bit Windows is supported. .. _MacPorts: https://www.macports.org/ .. _MSYS2: https://www.msys2.org/ .. _Repology: https://repology.org/ + +OS Support Tiers +---------------- + +While the QEMU code targets a number of different OS platforms, they don't +all get the same level of support from the project. This applies to +contributor & maintainer expectations, CI automation and requirements +for merge gating. + +Tier 1 +~~~~~~ + +These platforms attain the highest level of quality offered by +the QEMU project. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs all available tests frameworks (unit, qtest, iotests, functional) + in CI + + * Merging code is gated on successful CI jobs + +This covers + + * Linux (x86_64, aarch64, s390x) + +Responsibilities: + + * Contributors MUST test submitted patches on one of Tier 1 platforms. + + * Contributors SHOULD test submitted patches on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST request contributors to fix problems with Tier 1 + platforms. + + * Maintainers MUST test pull requests on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge immediately. + + +Tier 2 +~~~~~~ + +These platforms are considered to be near Tier 1 level, but are +lacking sufficient automated CI testing cover to guarantee this. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs some test frameworks in CI + +This covers + + * Linux (mips64el, ppc64el, riscv64) + + * FreeBSD (x86_64) + + * macOS (aarch64) + + * Windows (x86_64) + +Responsibilities: + + * Contributors MAY test patches on Tier 2 platforms + by running a GitLab CI pipeline in their fork + + * Maintainers SHOULD request contributors to fix problems with Tier 2 + platforms. + + * Maintainers MUST test pull requests on all Tier 2 platforms, + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge quickly. + + +Tier 3 +~~~~~~ + +These platforms have theoretical support in the code, but have +little, or no, automated build and test coverage. Downstream +consumers (users or distributors) who care about these platforms +are requested to perform manual testing, report bugs and provide +patches. + + * Builds and tests may be broken at any time in Git HEAD and + releases + + * Builds are not integrated into CI + + * Tests are not integrated into CI + + * Merging code is not gated + +This covers: + + * NetBSD + * OpenBSD + * macOS (except aarch64) + * FreeBSD (except x86_64) + * Windows (except x86_64) + * Solaris + +Responsibilities: + + * Contributors MAY test patches on Tier 3 platforms manually + + * Maintainers MAY request contributors to fix problems + on Tier 3 platforms + + * Maintainers MAY test patches on Tier 3 platforms manually + + * Maintainers SHOULD NOT accept patches that remove code + targetting Tier 3 platforms even if currently broken + + * Downstream vendors SHOULD test RC releases on Tier 3 platforms + and provide bug reports and patches to address problems + +Note: if a Tier 3 platform is found to be significantly broken, +no patches are contributed for a prolonged period, and there is +no sign of downstream usage, it is liable to be moved to +"Unclassified" and thus be subject to removal. + + +Unclassified +~~~~~~~~~~~~ + +These platforms are not intended to be supported in the code +and outside the scope of any support tiers. + + * Code supporting these platforms can removed at any time + * Bugs reports related to these platforms will generally + be ignored + +This covers: +
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 325
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+ * All 32-bit architectures on any OS + * Any OS not listed above + +Responsibilities: + + * Maintainers MAY decline patches that add code targetting + unclassified platforms + + * Maintainers MAY accept patches that remove code targetting + unclassified platforms
That's a good summary, but it should differentiate testing/runtime issues from building issues.
In general, maintainers should ensure code build on all platforms/configs. Of course, it's a best effort considering not all of them are built in CI, but in case a build issue is caught on time, it should be fixed before hitting master.
It may be worth to mention that all platforms can be accessed for free using: https://github.com/second-reality/github-runners.
If you're open to it, we could move this project under https://github.com/qemu and preinstall all dependencies on each runner, so people can easily jump on a shell and start debugging things without wasting time.
With this at hand, there is no reason to let a build failure be merged.
Thanks,
Pierrick
Quoted 199 lines · Pierrick Bouvier
Quoted 184 lines · Daniel P. Berrangé
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
Signed-off-by Daniel P. Berrangé <[email protected]>---
This came out of the discussion about recent unnoticed breakage in NetBSD builds and what maintainers are expected todo about it (if anything)
https://lists.nongnu.org/archive/html/qemu-devel/2026-01/msg02543.htmldocs/about/build-platforms.rst | 152 +++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+)docs/about/build-platforms.rst +142
-0@@ -171,3 +171,155 @@ Only 64-bit Windows is supported. .. _MacPorts: https://www.macports.org/ .. _MSYS2: https://www.msys2.org/ .. _Repology: https://repology.org/ + +OS Support Tiers +---------------- + +While the QEMU code targets a number of different OS platforms, they don't +all get the same level of support from the project. This applies to +contributor & maintainer expectations, CI automation and requirements +for merge gating. + +Tier 1 +~~~~~~ + +These platforms attain the highest level of quality offered by +the QEMU project. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs all available tests frameworks (unit, qtest, iotests, functional) + in CI + + * Merging code is gated on successful CI jobs + +This covers + + * Linux (x86_64, aarch64, s390x) + +Responsibilities: + + * Contributors MUST test submitted patches on one of Tier 1 platforms. + + * Contributors SHOULD test submitted patches on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST request contributors to fix problems with Tier 1 + platforms. + + * Maintainers MUST test pull requests on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge immediately. + + +Tier 2 +~~~~~~ + +These platforms are considered to be near Tier 1 level, but are +lacking sufficient automated CI testing cover to guarantee this. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs some test frameworks in CI + +This covers + + * Linux (mips64el, ppc64el, riscv64) + + * FreeBSD (x86_64) + + * macOS (aarch64) + + * Windows (x86_64) + +Responsibilities: + + * Contributors MAY test patches on Tier 2 platforms + by running a GitLab CI pipeline in their fork + + * Maintainers SHOULD request contributors to fix problems with Tier 2 + platforms. + + * Maintainers MUST test pull requests on all Tier 2 platforms, + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge quickly. + + +Tier 3 +~~~~~~ + +These platforms have theoretical support in the code, but have +little, or no, automated build and test coverage. Downstream +consumers (users or distributors) who care about these platforms +are requested to perform manual testing, report bugs and provide +patches. + + * Builds and tests may be broken at any time in Git HEAD and + releases + + * Builds are not integrated into CI + + * Tests are not integrated into CI + + * Merging code is not gated + +This covers: + + * NetBSD + * OpenBSD + * macOS (except aarch64) + * FreeBSD (except x86_64) + * Windows (except x86_64) + * Solaris + +Responsibilities: + + * Contributors MAY test patches on Tier 3 platforms manually + + * Maintainers MAY request contributors to fix problems + on Tier 3 platforms + + * Maintainers MAY test patches on Tier 3 platforms manually + + * Maintainers SHOULD NOT accept patches that remove code + targetting Tier 3 platforms even if currently broken + + * Downstream vendors SHOULD test RC releases on Tier 3 platforms + and provide bug reports and patches to address problems + +Note: if a Tier 3 platform is found to be significantly broken, +no patches are contributed for a prolonged period, and there is +no sign of downstream usage, it is liable to be moved to +"Unclassified" and thus be subject to removal. + + +Unclassified +~~~~~~~~~~~~ + +These platforms are not intended to be supported in the code +and outside the scope of any support tiers. + + * Code supporting these platforms can removed at any time + * Bugs reports related to these platforms will generally + be ignored + +This covers: +docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 325
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+ * All 32-bit architectures on any OS + * Any OS not listed above + +Responsibilities: + + * Maintainers MAY decline patches that add code targetting + unclassified platforms + + * Maintainers MAY accept patches that remove code targetting + unclassified platformsThat's a good summary, but it should differentiate testing/runtime issues from building issues.
Quoted 4 lines
In general, maintainers should ensure code build on all platforms/configs. Of course, it's a best effort considering not all of them are built in CI, but in case a build issue is caught on time, it should be fixed before hitting master.
It is certainly the case for Tier 1/2 platforms, that a known build issue must not be willfully merged into master.
That's not the case for Tier 3, since we can't guarantee that the QEMU code builds successfully to begin with. If we do a see a probable issue in a Tiar 3 platform build, and its easy to resolve then we should. We can't gate on every Tier 3 problem given the lack of guaranteed working dev/test envs and lack of CI.
Ideally we should not have any platforms listed under Tier 3 at all, but today we do. May be some will graduate to Tier 2 at some point.
Quoted 6 lines
It may be worth to mention that all platforms can be accessed for free
using: https://github.com/second-reality/github-runners.
If you're open to it, we could move this project under
https://github.com/qemu and preinstall all dependencies on each runner, so people can easily jump on a shell and start debugging things without wasting time.
I don't speak for all maintainers, but personally I've no desire to increase use of github for QEMU, or indeed any other projects.
The choice of platform is about more than just possible features. The ability to control our own destiny, and maintain use of OSS infrastructure was/is important.
GitLab is certainly not perfect, but gitlab.com was an acceptable tradeoff with the ability to switch to self-hosted Gitlab since it is based on OSS. Beyond that we could also migrate to Forgejo/ Codeberg. Tieing ourselves into GitHub's fully proprietary service has never really been on the table for QEMU.
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
Quoted 205 lines · Daniel P. Berrangé
Quoted 199 lines · Pierrick Bouvier
Quoted 184 lines · Daniel P. Berrangé
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
Signed-off-by Daniel P. Berrangé <[email protected]>---
This came out of the discussion about recent unnoticed breakage in NetBSD builds and what maintainers are expected todo about it (if anything)
https://lists.nongnu.org/archive/html/qemu-devel/2026-01/msg02543.htmldocs/about/build-platforms.rst | 152 +++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+)docs/about/build-platforms.rst +142
-0@@ -171,3 +171,155 @@ Only 64-bit Windows is supported. .. _MacPorts: https://www.macports.org/ .. _MSYS2: https://www.msys2.org/ .. _Repology: https://repology.org/ + +OS Support Tiers +---------------- + +While the QEMU code targets a number of different OS platforms, they don't +all get the same level of support from the project. This applies to +contributor & maintainer expectations, CI automation and requirements +for merge gating. + +Tier 1 +~~~~~~ + +These platforms attain the highest level of quality offered by +the QEMU project. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs all available tests frameworks (unit, qtest, iotests, functional) + in CI + + * Merging code is gated on successful CI jobs + +This covers + + * Linux (x86_64, aarch64, s390x) + +Responsibilities: + + * Contributors MUST test submitted patches on one of Tier 1 platforms. + + * Contributors SHOULD test submitted patches on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST request contributors to fix problems with Tier 1 + platforms. + + * Maintainers MUST test pull requests on Tier 1 platforms + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge immediately. + + +Tier 2 +~~~~~~ + +These platforms are considered to be near Tier 1 level, but are +lacking sufficient automated CI testing cover to guarantee this. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs some test frameworks in CI + +This covers + + * Linux (mips64el, ppc64el, riscv64) + + * FreeBSD (x86_64) + + * macOS (aarch64) + + * Windows (x86_64) + +Responsibilities: + + * Contributors MAY test patches on Tier 2 platforms + by running a GitLab CI pipeline in their fork + + * Maintainers SHOULD request contributors to fix problems with Tier 2 + platforms. + + * Maintainers MUST test pull requests on all Tier 2 platforms, + by running a GitLab CI pipeline in their fork. + + * Maintainers MUST co-ordinate fixing regressions identified + post-merge quickly. + + +Tier 3 +~~~~~~ + +These platforms have theoretical support in the code, but have +little, or no, automated build and test coverage. Downstream +consumers (users or distributors) who care about these platforms +are requested to perform manual testing, report bugs and provide +patches. + + * Builds and tests may be broken at any time in Git HEAD and + releases + + * Builds are not integrated into CI + + * Tests are not integrated into CI + + * Merging code is not gated + +This covers: + + * NetBSD + * OpenBSD + * macOS (except aarch64) + * FreeBSD (except x86_64) + * Windows (except x86_64) + * Solaris + +Responsibilities: + + * Contributors MAY test patches on Tier 3 platforms manually + + * Maintainers MAY request contributors to fix problems + on Tier 3 platforms + + * Maintainers MAY test patches on Tier 3 platforms manually + + * Maintainers SHOULD NOT accept patches that remove code + targetting Tier 3 platforms even if currently broken + + * Downstream vendors SHOULD test RC releases on Tier 3 platforms + and provide bug reports and patches to address problems + +Note: if a Tier 3 platform is found to be significantly broken, +no patches are contributed for a prolonged period, and there is +no sign of downstream usage, it is liable to be moved to +"Unclassified" and thus be subject to removal. + + +Unclassified +~~~~~~~~~~~~ + +These platforms are not intended to be supported in the code +and outside the scope of any support tiers. + + * Code supporting these platforms can removed at any time + * Bugs reports related to these platforms will generally + be ignored + +This covers: +docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 325
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+ * All 32-bit architectures on any OS + * Any OS not listed above + +Responsibilities: + + * Maintainers MAY decline patches that add code targetting + unclassified platforms + + * Maintainers MAY accept patches that remove code targetting + unclassified platformsThat's a good summary, but it should differentiate testing/runtime issues from building issues.
Quoted 4 lines
In general, maintainers should ensure code build on all platforms/configs. Of course, it's a best effort considering not all of them are built in CI, but in case a build issue is caught on time, it should be fixed before hitting master.
Quoted 9 lines
It is certainly the case for Tier 1/2 platforms, that a known build issue must not be willfully merged into master.
That's not the case for Tier 3, since we can't guarantee that the QEMU code builds successfully to begin with. If we do a see a probable issue in a Tiar 3 platform build, and its easy to resolve then we should. We can't gate on every Tier 3 problem given the lack of guaranteed working dev/test envs and lack of CI.
Sure, it can't be enforced automatically as you mentioned.
As you said, some maintainers may test some tier 3 platforms as part of their personal "check" routine, and in this case, they are allowed to ask to the developer to fix it, which your documentation mentions already. So far, so good.
However, this comes with the question of providing the developer a way to access those environments, as not everyone has an arm64 machine or a macos machine. And it's not far to ask people to fix something they don't have access to.
Thus the second point in my email, how to provide this?
Quoted 17 lines
Ideally we should not have any platforms listed under Tier 3 at all, but today we do. May be some will graduate to Tier 2 at some point.
Quoted 6 lines
It may be worth to mention that all platforms can be accessed for free
using: https://github.com/second-reality/github-runners.
If you're open to it, we could move this project under
https://github.com/qemu and preinstall all dependencies on each runner, so people can easily jump on a shell and start debugging things without wasting time.I don't speak for all maintainers, but personally I've no desire to increase use of github for QEMU, or indeed any other projects.
The choice of platform is about more than just possible features. The ability to control our own destiny, and maintain use of OSS infrastructure was/is important.
Quoted 6 lines
GitLab is certainly not perfect, but gitlab.com was an acceptable tradeoff with the ability to switch to self-hosted Gitlab since it is based on OSS. Beyond that we could also migrate to Forgejo/ Codeberg. Tieing ourselves into GitHub's fully proprietary service has never really been on the table for QEMU.
I respect your position and your dedication to using OSS. To a broader extent, I respect your view on what is acceptable or not for the project.
I *NEVER* mentioned I wanted to change anything to QEMU project whether it's relocating its source code, bug tracker, or even its CI. Personnally, I really like GitLab features and UI, much more than GitHub.
The goal is not to force anyone or QEMU to use GitHub, but to provide a free and open source solution to anyone who might want/need to access such machines. Nothing more.
It's simply because GitHub offers unlimited minutes for any public project. To give you a concrete number, in 2025, testing all qemu series, it used 50'000$ of CI minutes for... free. Personally, I think that's a good deal, and the best solution on the (free) market today. Every maintainer can see in seconds if any series builds, passes tests, or checkpatch, without wasting their personal "minutes". I started this for learning QEMU testing and for my personal usage, and realized it can be useful for maintainers also.
https://github.com/pbo-linaro/qemu-ci/branches/all
QEMU project uses runners from Digital Ocean, which we use only because we have free credits there. It's as closed as AWS, GCP or Azure. GitHub runners use Azure, and their VM images are fully open source by the way:
https://github.com/actions/runner-images
Finally, I would like to make an analogy, that may help to understand my pragmatic position on all this.
From your professional email signature, I already had the pleasure to visit your personal gallery and enjoy your photos, a hobby you and I have in common.
Have you been comfortable with using a Nikon camera that has a closed source firmware? I guess yes, because the edit and production chain you use are. Well, it's the same here. QEMU is built and produced with a chain we control, and that is OSS. Where we run our tests or play with it, well, it does not really matter and does not impact a single bit of our digital destiny.
Now, I invite you again to take 1 minute of your time, visit this link and read the README: https://github.com/second-reality/github-runners
You'll see there is nothing to be scared about, just a simple way to access various machines for free.
Regards,
Pierrick
Quoted 2 lines
With regards,
Daniel
Quoted 24 lines · Daniel P. Berrangé
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
Signed-off-by Daniel P. Berrangé <[email protected]>---
...
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 229
Quoted 12 lines
docs/about/build-platforms.rst +12
-0+ +Tier 2 +~~~~~~ + +These platforms are considered to be near Tier 1 level, but are +lacking sufficient automated CI testing cover to guarantee this. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs some test frameworks in CI
I don't think that we run any test frameworks for Linux on mips64el or riscv64 in the CI, do we? It's only cross-compilation of the code.
...
Quoted 17 lines
docs/about/build-platforms.rst +17
-0+ +Tier 3 +~~~~~~ + +These platforms have theoretical support in the code, but have +little, or no, automated build and test coverage. Downstream +consumers (users or distributors) who care about these platforms +are requested to perform manual testing, report bugs and provide +patches. + + * Builds and tests may be broken at any time in Git HEAD and + releases + + * Builds are not integrated into CI + + * Tests are not integrated into CI +
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 281
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+ * Merging code is not gated + +This covers: + + * NetBSD + * OpenBSD + * macOS (except aarch64) + * FreeBSD (except x86_64) + * Windows (except x86_64) + * Solaris
You missed Haiku.
Quoted 4 lines
docs/about/build-platforms.rst +4
-0+ +Unclassified +~~~~~~~~~~~~ +
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 316
Quoted 10 lines
docs/about/build-platforms.rst +10
-0+These platforms are not intended to be supported in the code +and outside the scope of any support tiers. + + * Code supporting these platforms can removed at any time + * Bugs reports related to these platforms will generally + be ignored + +This covers: + + * All 32-bit architectures on any OS
Support for 32-bit OSes is currently being removed.
Quoted 1 line
+ * Any OS not listed above
Is it possible at all to compile QEMU for any other OS? I though our configure script would block such attempts...?
Thomas
Quoted 26 lines · Thomas Huth
Quoted 24 lines · Daniel P. Berrangé
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
Signed-off-by Daniel P. Berrangé <[email protected]>---
...
Quoted 15 lines
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 229
Quoted 12 lines
docs/about/build-platforms.rst +12
-0+ +Tier 2 +~~~~~~ + +These platforms are considered to be near Tier 1 level, but are +lacking sufficient automated CI testing cover to guarantee this. + + * Builds and all tests pass at all times in both git HEAD and releases + + * Builds for multiple build configuration are integrated in CI + + * Runs some test frameworks in CII don't think that we run any test frameworks for Linux on mips64el or riscv64 in the CI, do we? It's only cross-compilation of the code.
I didn't want to put those in tier 3 since I think they're generally better than that. Perhaps this bullet should be loosened slightly
"May run some tests frameworks in CI"
Quoted 23 lines
...
Quoted 21 lines
docs/about/build-platforms.rst +21
-0+ +Tier 3 +~~~~~~ + +These platforms have theoretical support in the code, but have +little, or no, automated build and test coverage. Downstream +consumers (users or distributors) who care about these platforms +are requested to perform manual testing, report bugs and provide +patches. + + * Builds and tests may be broken at any time in Git HEAD and + releases + + * Builds are not integrated into CI + + * Tests are not integrated into CI + + * Merging code is not gated + +This covers: +
Quoted 8 lines
Quoted 6 lines
+ * NetBSD
+ * OpenBSD
+ * macOS (except aarch64)
+ * FreeBSD (exceptx86_64)
+ * Windows (exceptx86_64)
+ * SolarisYou missed Haiku.
Opps, I knew I'd miss something :-)
Quoted 8 lines
Quoted 8 lines
docs/about/build-platforms.rst +8
-0+ +Unclassified +~~~~~~~~~~~~ + +These platforms are not intended to be supported in the code +and outside the scope of any support tiers. + + * Code supporting these platforms can removed at any time
Quoted 8 lines
docs/about/build-platforms.rst Only 64-bit Windows is supported. · line 316
Quoted 6 lines
docs/about/build-platforms.rst +6
-0+ * Bugs reports related to these platforms will generally + be ignored + +This covers: + + * All 32-bit architectures on any OSSupport for 32-bit OSes is currently being removed.
Yep, this doc is slightly anticipating the future. I was expecting that Richard's series:
https://lists.nongnu.org/archive/html/qemu-devel/2026-01/msg03073.html
will be merged soon enough.
Quoted 4 lines
Quoted 1 line
+ * Any OS not listed above
Is it possible at all to compile QEMU for any other OS? I though our configure script would block such attempts...?
Hmm, true, we should be blocking atttempts to build. So anycode related to unclassified OS would be non-buildable and definitely OK to remove.
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
Quoted 25 lines · Daniel P. Berrangé
Informally we have approximately three groups of platforms
* Tier 1: fully built and fully tested by CI. Must always be kept working & regressions fixed immediately
* Tier 2: fully built and partially tested by CI. Should always be kept working & regressions fixed quickly
* Tier 3: code exists but is not built or tested by CI. Should not be intentionally broken but not guaranteed to work at any time. Downstream must manually test, report & fix bugs.
Anything else is "unclassified" and any historical code remnants may be removed.
It is somewhat tricky to define unambiguous rules for each tier, but this doc takes a stab at it. We don't need to cover every eventuality. If we get the core points of view across, then it at least sets the direction for maintainers/contributors/users. Other aspects can be inferred with greater accuracy than today.
Signed-off-by Daniel P. Berrangé <[email protected]>---
Quoted 8 lines
This came out of the discussion about recent unnoticed breakage in NetBSD builds and what maintainers are expected todo about it (if anything)
https://lists.nongnu.org/archive/html/qemu-devel/2026-01/msg02543.html
docs/about/build-platforms.rst | 152 +++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+)