Move rawhide gating docs to a separate repo
This commit is contained in:
parent
74f25cd503
commit
86f08a923b
9 changed files with 0 additions and 330 deletions
Binary file not shown.
|
Before Width: | Height: | Size: 243 KiB |
|
|
@ -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]
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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].
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue