diff --git a/antora.yml b/antora.yml index c8d46f4..92671d2 100644 --- a/antora.yml +++ b/antora.yml @@ -14,4 +14,3 @@ start_page: cpe:index # This lists all the menu definitions of your component. nav: - modules/cpe/nav.adoc -- modules/rawhide-gating/nav.adoc diff --git a/modules/rawhide-gating/assets/images/Rawhide-Package-Gating-Flow.jpg b/modules/rawhide-gating/assets/images/Rawhide-Package-Gating-Flow.jpg deleted file mode 100644 index ef680ff..0000000 Binary files a/modules/rawhide-gating/assets/images/Rawhide-Package-Gating-Flow.jpg and /dev/null differ diff --git a/modules/rawhide-gating/nav.adoc b/modules/rawhide-gating/nav.adoc deleted file mode 100644 index 2280bbe..0000000 --- a/modules/rawhide-gating/nav.adoc +++ /dev/null @@ -1,6 +0,0 @@ -* xref:rawhide-gating:index.adoc[Rawhide Gating] -** xref:rawhide-gating:workflows.adoc[Workflows] -** xref:rawhide-gating:optin.adoc[Opting in] -** xref:rawhide-gating:single-builds.adoc[Single Build updates] -** xref:rawhide-gating:multibuilds.adoc[Multibuilds updates] -** xref:rawhide-gating:faq.adoc[FAQ] diff --git a/modules/rawhide-gating/pages/faq.adoc b/modules/rawhide-gating/pages/faq.adoc deleted file mode 100644 index 34f3912..0000000 --- a/modules/rawhide-gating/pages/faq.adoc +++ /dev/null @@ -1,61 +0,0 @@ -:experimental: -:toc: -= Frequently asked questions - -== What if I don't want to use gating? - -While we believe CI and gating will ultimately help making a better Fedora, -nothing is being enforced at this point. Keep packaging as you do now! - -== How do I opt in? -We are so glad you're asking us this question :) - -There are two steps to do to opt-in the gating: - -* Add tests to your package -* Configure gating, so that your package is gated on those tests - -We go over both of them in our xref:rawhide-gating:optin.adoc[opting in] page. - -== Something doesn't work! -That's not a question! Anyway, bugs will be bugs. -This is the first roll-out of this change, and more will come. -This rollout lets us gather feedback and iterate on the approach in an -open source fashion. - -* If you did not opt-in and you can’t do your packaging work as you used to, -please file an link:++https://pagure.io/fedora-infrastructure/new_issue?title=[CI]%20it%20doesn%27t%20work%20as%20I%20want++[infrastructure ticket], -since it’s likely a bug. -* If you did opt-in and something in the gating of your update doesn’t work -(for example, CI ran but its results aren’t being considered, waiving didn’t work…), -file an link:++https://pagure.io/fedora-infrastructure/new_issue?title=[CI]++[infrastructure ticket]. -* If you opted-in and the tests don’t run the way you expect, file a -link:https://pagure.io/fedora-ci/general/new_issue[fedora-ci ticket]. - -== How do I re-trigger a test run? - -Sometime infra fails on us, networking or something else messes with us and -the tests that we rely on suddenly are no longer passing. - -Unfortunately, at this point it is not possible to re-trigger a test run. -This is something that is on our roadmap and that we will get to ASAP but -it is just not here in this early stage. -You can bump the version and do a new build or see the next section to -unblock you if you need to. - -== How do I unblock an update? - -You shouldn't need to unblock an update, either the tests need to be fixed -or the code being tested. -This is however the theory and in practice sometime we have to :( - -The CI documentation covers link:https://docs.fedoraproject.org/en-US/ci/gating/#_waive[how to waive] - -If you want a clue try running: - bodhi updates waive --help - -== How do I opt out after previously opting in? -`:sad trombone:` - -We hope you reported all the issues you have found/faced and are helping us resolving them. -In the meanwhile, you can simply remove the `gating.yaml` file you added to your git repository during the opt-in process; greenwave will then ignore your package. diff --git a/modules/rawhide-gating/pages/index.adoc b/modules/rawhide-gating/pages/index.adoc deleted file mode 100644 index ae054c4..0000000 --- a/modules/rawhide-gating/pages/index.adoc +++ /dev/null @@ -1,40 +0,0 @@ -:experimental: -= Fedora Rawhide Gating - -The following several pages document newly enabled gating in Fedora Rawhide. - -The aim of this initiative is to set up the infrastructure so that packages can be gated based on test results before they are allowed into Fedora Rawhide. -This will reduce the amount of broken dependencies, uninstallable packages, and broken composes, leading to a more stable Rawhide. -As an added benefit this framework will also lessen the burden on the infrastructure and release engineering teams that ensure composes keep working. - -== Reasoning for gating - -The basic principle of this proposal is to provide an environment in which packages can be built and tested without affecting other packages. - -When considering gating Rawhide package updates on test results, we need to consider two workflows: single build updates and multi-build updates. - -* For a xref:single-builds.adoc[single build], the easiest solution is to provide a dedicated Koji tag in which these packages are built, and where they is wait for their tests to pass before they can enter the buildroot. -* For xref:multibuilds.adoc[multi-builds], the solution is be to rely on "side-tags" in Koji. -These side-tags are basically tags created by the packager and available to them to do their work, in this case rebuild all the packages desired. -The side-tag can then sent to the test system as being one unit of change. - -To use a now well-known analogy, a single-build update is like sending a commit to a mailing list; it waits there to be reviewed and tested before being merged into the main repository. -Multi-build updates are more similar to pull-requests - they can contain one or more builds which are reviewed and tested all together as one change before being merged. - -Rawhide is an unique place in the Fedora ecosystem. -It is the only place where large changes and rebuilds can be done. -In stable Fedora releases, the rebuilds of large sets of packages is discouraged by the packaging guidelines, so the ratio of number single and multi-builds in Bodhi (95% to 5%) is not reflective of the reality of the Rawhide ecosystem. - -With Rawhide Gating, the aim is to build the infrastructure allowing to gate packages in Rawhide. -The idea is for packages to go through Bodhi, be tested and if the tests pass, and land in the Rawhide buildroot as they do today. -In the simplest case, the packager workflow will not be affected by this proposal; more complicated situations will require adjustements to the packager workflow. -However, these adjustments are minimal. - -**No tests are being made mandatory as this framework is introduced.** -It is up to the community (and xref:fesco::index.adoc[FESCo]) to decide if any rules should be enforced for all packages, and if yes, what rules they should be. - -== Additional reading - -* xref:faq.adoc[Frequently asked questions] provides answers to frequently asked questions about Rawhide gating. -* xref:ci::index.adoc[Fedora CI documentation] has information about continuous integration in Fedora. -* xref:ci::quick-start-guide.adoc[Fedora CI quick start guide] gives you the basic about Fedora CI in one place. diff --git a/modules/rawhide-gating/pages/multibuilds.adoc b/modules/rawhide-gating/pages/multibuilds.adoc deleted file mode 100644 index 4c50afa..0000000 --- a/modules/rawhide-gating/pages/multibuilds.adoc +++ /dev/null @@ -1,31 +0,0 @@ -:experimental: -= Multibuilds - -We are working on this workflow and we will update this page and send -announcement when it is ready or available for testing. - -You can find some hints about the direction we are following in: - -- Our change proposal (the one approved by FESCo): - link:https://fedoraproject.org/wiki/Changes/GatingRawhidePackages[] -- Our project's requirement document - link:https://fedoraproject.org/wiki/Infrastructure_2020/Rawhide_Gating[] - - -== What are multi-builds updates? - -Multi-builds updates are builds that are tightly coupled to other build(s). - -For compiled package that rely on a certain ABI or soname, it is easy to -understand how they are tightly coupled. However, non-compiled programs can -also have this strong dependencies. - -For example, the packages link:https://src.fedoraproject.org/rpms/python-urllib3[rpms/python-urllib3] -and link:https://src.fedoraproject.org/rpms/python-requests/[rpms/python-requests] -are heavily linked. Updates to python-urllib3 need to take python-requests -into consideration. Sometime the update is fine, sometime it needs to wait -for a new version of python-requests, in which case both builds need to be -tested together as one unit. - -These package are candidates for the multi-builds updates workflow. They -need to be built and tested together. diff --git a/modules/rawhide-gating/pages/optin.adoc b/modules/rawhide-gating/pages/optin.adoc deleted file mode 100644 index c4e890f..0000000 --- a/modules/rawhide-gating/pages/optin.adoc +++ /dev/null @@ -1,89 +0,0 @@ -:experimental: -= How to opt-in into gating? - -There are two steps to do to opt-in the rawhide gating: - -* Add tests to your package -* Configure gating, so that your package is gated on those tests - -== Add tests to your package - -You can add tests by following the -link:https://docs.fedoraproject.org/en-US/ci/tests/#_writing[documentation -on how to write tests]. - -The gist of it is: Add a `tests` folder in the git repository of your -package and place a `tests.yml` in it. That file should be an -link:http://docs.ansible.com/ansible/latest/playbooks.html[ansible playbook] -with all the steps to reproduce to test your package. - -IMPORTANT: You need to "tag" the playbook with any or all of the following tags - so the tests can be called in the different environments: - `classic`, `container`, `atomic` - -Once you have added a `tests/tests.yml` for every update you created for that -package the tests will be run and will show in the update page under the -test results tab. - -For these tests to have an effect, you need to configure the system to gate -on them. - -== Configure gating - -To configure the system to gate your package on tests, you need to add a -`gating.yaml` to the git repository of the package(s) you want gated. - - -A simple `gating.yaml` will look like this: - -.... ---- !Policy -product_versions: - - fedora-* -decision_context: bodhi_update_push_testing -subject_type: koji_build -rules: - - !PassingTestCaseRule {test_case_name: org.centos.prod.ci.pipeline.allpackages-build.complete} ---- !Policy -product_versions: - - fedora-* -decision_context: bodhi_update_push_stable -subject_type: koji_build -rules: - - !PassingTestCaseRule {test_case_name: org.centos.prod.ci.pipeline.allpackages-build.complete} -.... - -Basically, it contains two policies, one to push a build to testing and one -to push a build to stable and for both of these situations, it asks that the -test named `org.centos.prod.ci.pipeline.allpackages-build.complete` passes. - -If gating on your package-level tests is all that interest you, you can -use this example as is. - -If you are also interested in some of the taskotron checks, such as: -`dist.python-versions` or `dist.python-versions.py3_support`, you could -ammend the file so it looks like: -.... ---- !Policy -product_versions: - - fedora-* -decision_context: bodhi_update_push_testing -subject_type: koji_build -rules: - - !PassingTestCaseRule {test_case_name: org.centos.prod.ci.pipeline.allpackages-build.complete} - - !PassingTestCaseRule {test_case_name: dist.python-versions} - - !PassingTestCaseRule {test_case_name: dist.python-versions.py3_support} ---- !Policy -product_versions: - - fedora-* -decision_context: bodhi_update_push_stable -subject_type: koji_build -rules: - - !PassingTestCaseRule {test_case_name: org.centos.prod.ci.pipeline.allpackages-build.complete} - - !PassingTestCaseRule {test_case_name: dist.python-versions} - - !PassingTestCaseRule {test_case_name: dist.python-versions.py3_support} -.... - - -You can find more about this file in greenwave's documentation about -link:https://docs.pagure.org/greenwave/package-specific-policies.html[package specific policies]. diff --git a/modules/rawhide-gating/pages/single-builds.adoc b/modules/rawhide-gating/pages/single-builds.adoc deleted file mode 100644 index 935b893..0000000 --- a/modules/rawhide-gating/pages/single-builds.adoc +++ /dev/null @@ -1,52 +0,0 @@ -:experimental: -= Single Build updates - -== What are single build updates? - -Single build updates are builds that do not depend tightly on other build(s). - -For example, the package link:https://src.fedoraproject.org/rpms/pass[rpms/pass] -is a simple bash script coming with some documentation and utilities (for -emacs, vim or zsh). It has a dependencies on git, gnupg2, perl-generators -and tree to build and xclip in addition to these for running. -It is not tighly depending on any specific version for any of these (it only -has a minimal required version for tree). -It does not rely on any ABI, does not need to be rebuild on soname changes -or updates. - -These packages are candidates for single build updates. They can be built -and tested by themselves. - -== How does gating single build updates work? - -Single build updates are easy to gate since they can be tested in isolation -from the other builds. -That is, the CI system can take the build, test it, gate it or late it go -through, without having to consider any other changes (ie: packages/builds). - -So the workflow is the following: - -- When you build your package for rawhide, it lands in a default koji tags - (the candidate tag) -- robosignatory is notified of your build landing in this tag by our message - bus, so it will take the build, sign it and move it into another koji tag - (the updates-testing-pending tag) -- bodhi will be notified of your build landing in that koji tag by our - message bus. It will automatically create an update for this build, in your - name. That update will automatically be of the `Testing` status. -- Tests will run, report their results to resultsdb which will announce these - results, making greenwave query your `gating.yaml` to see if all the required - criteria of this build have been met or not. If they have, greenwave will - send a message to the message bus announcing its decision. -- bodhi will listen for these messages from greenwave. Upon receiving them - it will push the corresponding build into final koji tag (the stable tag) - and mark the update as stable. - -At this point, your build has landed to the stable tag in koji, it is therefore -available in the buildroot for anyone to use and rely on and the corresponding -bodhi update has been marked as stable. - -IMPORTANT: Note that the update being `stable` does not mean you will be able - to install it via dnf/yum. It means the build is available in the rawhide - builroot. It will be pushed to the mirror once the next rawhide compose - succeeds. diff --git a/modules/rawhide-gating/pages/workflows.adoc b/modules/rawhide-gating/pages/workflows.adoc deleted file mode 100644 index 2d4d062..0000000 --- a/modules/rawhide-gating/pages/workflows.adoc +++ /dev/null @@ -1,50 +0,0 @@ -:experimental: - -= Rawhide Gating workflows - -When considering gating packages for rawhide, two situations can be -distinguished: packages/builds that can be tested by themselves and -packages/builds that need to be tested together. - -This is the basis for the single-build updates vs multi-builds updates that -you will find all the way through this documents. - - -The following diagrams represent the flow between the different pieces of -the infrastructure use to gate packages in Rawhide. (Click the images to -view a larger version.) - - -== Single build updates - -The following diagram represent the flow between the different pieces of -the infrastructure use to gate single-build updates in rawhide. - -[link=../_images/Rawhide-Package-Gating-Flow.jpg] -image::{imagesdir}/Rawhide-Package-Gating-Flow.jpg[] - -The diagram shows all the services and application involved in gating -single-build updates in Rawhide. - -Our xref:single-builds.adoc[documentation on single build updates] goes -(with a little less details) through what this diagram presents graphically. - -It can also help you figure out how to debug something that is not behaving -as it should. - -The following links can help you figure out the state of a build or an -update if something seems stuck: - -* Jenkins pipelines: -** link:https://jenkins-continuous-infra.apps.ci.centos.org/view/Fedora%20All%20Packages%20Pipeline/job/fedora-rawhide-build-pipeline/[Rawhide] -** link:https://jenkins-continuous-infra.apps.ci.centos.org/view/Fedora%20All%20Packages%20Pipeline/job/fedora-f30-build-pipeline/[F30] -* link:https://jenkins-continuous-infra.apps.ci.centos.org/view/Fedora%20All%20Packages%20Pipeline/job/fedora-rawhide-build-pipeline/[resultsdb results from the CI pipeline] -* link:https://apps.fedoraproject.org/datagrepper/raw?category=resultsdb&rows_per_page=5&delta=127800[resultsdb's messages in datagrepper] -* Greenwave reacts to resultsdb, so you can check its link:https://apps.fedoraproject.org/datagrepper/raw?category=greenwave&rows_per_page=5&delta=127800[messages] as well - - - -== Multi-builds updates - -We are working on this workflow and we will update this page and send -announcement when it is ready or available for testing.