From 1b7d059a7b207553e96cfe66aec18d82a2d800ad Mon Sep 17 00:00:00 2001 From: Otto Liljalaakso Date: Jul 19 2024 14:35:56 +0000 Subject: [PATCH 1/3] Package Update Guide: Give names to different update workflows Previously, the different workflows used before and after updates-testing activation did not have clear names. Instead, they were referred to by explaining the difference every time, with quite many words. Simplify the text by naming them _before updates-testing activation_ and _after updates-testing_activation_. --- diff --git a/modules/ROOT/pages/Package_Update_Guide.adoc b/modules/ROOT/pages/Package_Update_Guide.adoc index d402a0a..9a4f6b1 100644 --- a/modules/ROOT/pages/Package_Update_Guide.adoc +++ b/modules/ROOT/pages/Package_Update_Guide.adoc @@ -21,11 +21,12 @@ This page specifically covers the update submission process. There are two significantly different package update submission workflows in Fedora: -* xref:releases::rawhide.adoc[Rawhide] -and xref:releases::branched.adoc[Branched] up to the xref:fesco::Updates_Policy.adoc#updates-testing-activation[Updates-testing Activation]. +* _Before updates-testing activation_, + which is used for xref:releases::rawhide.adoc[Rawhide] and xref:releases::branched.adoc[Branched] + up to the xref:fesco::Updates_Policy.adoc#updates-testing-activation[Updates-testing Activation]. -* Branched releases after Updates-testing Activation, -and stable releases. +* _After updates-testing activation_, + which is used for Branched releases after Updates-testing Activation, and stable releases. The repository layouts differ somewhat for Rawhide, Branched and stable releases, but the update workflows split up as described above. @@ -36,7 +37,7 @@ and multi-package updates. [#rawhide_and_early_branched] [#single_packages] -== Single-package updates for Rawhide and early Branched +== Single-package updates before updates-testing activation Most packages can be updated alone, without needing to be grouped with other packages @@ -46,7 +47,7 @@ If the change you are making affects other packages, see xref:multiple_packages[Multi-package updates]. The update workflow for single package builds -in Rawhide and Branched before updates-testing activation +before updates-testing activation is simple: . Build the package with `fedpkg build`. See xref:Package_Maintenance_Guide.adoc[Package Maintenance Guide] for more details. @@ -78,7 +79,7 @@ before waiving a failure. [#later_branched_and_stable_releases] -== Single-package updates for later Branched and stable releases +== Single-package updates after updates-testing activation At the https://docs.fedoraproject.org/en-US/fesco/Updates_Policy/#updates-testing-activation[updates-testing activation] point, the Bodhi update feedback system is enabled by https://docs.pagure.org/releng/[Release Engineering] @@ -471,7 +472,7 @@ which also has some instructions on usage. [#who_will_receive_your_update_when] === Who will receive your update, when? -For Rawhide and Branched before updates-testing activation, +Before updates-testing activation, when an update goes _stable_ it is tagged for inclusion in the next compose. Composes are usually run daily at 05:15 UTC and take several hours. After a compose completes, From afe1fc2749bbad7c7c18a9b26a42d8f4001bc07c Mon Sep 17 00:00:00 2001 From: Otto Liljalaakso Date: Jul 19 2024 14:38:03 +0000 Subject: [PATCH 2/3] Package Update Guide: Fix section levels Some sections were put under section _Multi-package updates_, even though they applied equally to single-package updates. Move them to higher level to avoid confusion and make the table of contents easier to understand. --- diff --git a/modules/ROOT/pages/Package_Update_Guide.adoc b/modules/ROOT/pages/Package_Update_Guide.adoc index 9a4f6b1..45d690b 100644 --- a/modules/ROOT/pages/Package_Update_Guide.adoc +++ b/modules/ROOT/pages/Package_Update_Guide.adoc @@ -399,7 +399,7 @@ Unlike with side tags, buildroot overrides are not isolated and thus should be only used in special cases where side tags do not suffice. [#handling_feedback_from_automated_tests] -=== Handling feedback from automated tests +== Handling feedback from automated tests Fedora's automated testing systems, including Fedora CI, openQA, and Fedora CoreOS CI, @@ -442,7 +442,7 @@ and will usually resolve them or post a comment on the update explaining the problem and suggesting a resolution. [#waive_a_result] -==== Waive a result +=== Waive a result Any failure of a gating test will prevent your update from being released. On the update's _Details_ page in the Bodhi web interface, @@ -470,7 +470,7 @@ You can get it from the https://pagure.io/waiverdb[the waiverdb repository], which also has some instructions on usage. [#who_will_receive_your_update_when] -=== Who will receive your update, when? +== Who will receive your update, when? Before updates-testing activation, when an update goes _stable_ it is tagged for inclusion in the next compose. @@ -509,7 +509,7 @@ this is an insignificant implementation detail. For more details, see xref:quick-docs::repositories.adoc[Repositories]. [#branched_milestone_freezes] -=== Branched milestone freezes +== Branched milestone freezes For a short period before each milestone release, the stable xref:quick-docs::repositories.adoc#the-fedora-repository-in-branched-releases[fedora] repository is frozen. From 8c5ea8b5c08c036552b55519759f194da8f91f98 Mon Sep 17 00:00:00 2001 From: Otto Liljalaakso Date: Jul 19 2024 14:38:11 +0000 Subject: [PATCH 3/3] Package Update Guide: Move _Update attributes_ section to higher level Section _Update attributes_ was under the section about singe-package updates, but its content applies equally to multi-package updates. Move it to correct level in the section hierarchy. --- diff --git a/modules/ROOT/pages/Package_Update_Guide.adoc b/modules/ROOT/pages/Package_Update_Guide.adoc index 45d690b..989972a 100644 --- a/modules/ROOT/pages/Package_Update_Guide.adoc +++ b/modules/ROOT/pages/Package_Update_Guide.adoc @@ -114,69 +114,8 @@ you should fix the problem, send a new build, and edit it into the update. -[#update_attributes] -=== Update attributes - -At the time you submit the update, -you will be asked for several attributes. -The type of the update should be fairly self-explanatory: -Either it fixes bugs, -adds new features, -or is a new package. - -If you are asked whether you want to send the update -to _updates-testing_ or _stable_, -this is a no-op: -all updates now go through _updates-testing_. It does not matter what you choose. - -There are several schools of thought -on filling out the update description. -Some would suggest you consider the target audience: -for a stable release, in particular, many Fedora users will see this text, -and many of them may not be particularly familiar with your package. -Consider not simply describing literally the changes in the update, -but explaining as if to an outsider -why your are updating the package, -what benefits it will bring to them (if any), -and anything they may want to note -in order to have a smooth update experience. - -If you associate one or more bug reports with your update, -Bodhi will post comments into Bugzilla -to alert those following the bug reports -that an update is available. -If you mark your update as fixing the bug(s), -Bodhi will move the report(s) through -the `MODIFIED`, `ON_QA` and `CLOSED ERRATA` states -of the xref:bug_status.adoc[Bug Status Workflow] -as your update reaches various points in the process. -Using this mechanism can be very useful -both for you and for users of your package. - -You may set thresholds for automatic push to stable -based on positive feedback (karma) -and/or time spent in updates-testing. -If your update's total karma -(items of positive feedback minus items of negative feedback) -reaches the karma threshold, it will be pushed stable automatically. -If your update reaches the threshold for time in updates-testing -without the builds changing -or the total karma going so low it is unpushed, -it will be pushed stable automatically. - -There are defaults for these thresholds -which vary at different points in the release process. - -If you choose to use the karma auto-push threshold, -please carefully consider an appropriate feedback level. -For a relatively obscure package which is quite stable, -1 or 2 may be an appropriate value. -For a popular, sensitive and complex package -such as `firefox` or `kernel`, -the default may be insufficient -and a choice of 5 -or even 10 -may be appropriate. +At the time you submit the update, you will be asked for several attributes. +See section xref:update_attributes[Update attributes] for guidance. [#multiple_packages] == [[updating_inter_dependent_packages]] Multi-package updates @@ -280,7 +219,7 @@ bodhi updates new --from-tag --notes "whatever" f{NEXTOSVER}-build-side-7863 ---- For more general information on creating updates, -see xref:update_attributes[Update attributes] above. +see xref:update_attributes[Update attributes]. Once the update is created, it will behave similarly to a single-package update. For Rawhide and early Branched, @@ -398,6 +337,70 @@ when the packages have build-time interdependencies. Unlike with side tags, buildroot overrides are not isolated and thus should be only used in special cases where side tags do not suffice. +[#update_attributes] +== Update attributes + +At the time you submit an update, +you will be asked for several attributes. +The type of the update should be fairly self-explanatory: +Either it fixes bugs, +adds new features, +or is a new package. + +If you are asked whether you want to send the update +to _updates-testing_ or _stable_, +this is a no-op: +all updates now go through _updates-testing_. It does not matter what you choose. + +There are several schools of thought +on filling out the update description. +Some would suggest you consider the target audience: +for a stable release, in particular, many Fedora users will see this text, +and many of them may not be particularly familiar with your package. +Consider not simply describing literally the changes in the update, +but explaining as if to an outsider +why your are updating the package, +what benefits it will bring to them (if any), +and anything they may want to note +in order to have a smooth update experience. + +If you associate one or more bug reports with your update, +Bodhi will post comments into Bugzilla +to alert those following the bug reports +that an update is available. +If you mark your update as fixing the bug(s), +Bodhi will move the report(s) through +the `MODIFIED`, `ON_QA` and `CLOSED ERRATA` states +of the xref:bug_status.adoc[Bug Status Workflow] +as your update reaches various points in the process. +Using this mechanism can be very useful +both for you and for users of your package. + +You may set thresholds for automatic push to stable +based on positive feedback (karma) +and/or time spent in updates-testing. +If your update's total karma +(items of positive feedback minus items of negative feedback) +reaches the karma threshold, it will be pushed stable automatically. +If your update reaches the threshold for time in updates-testing +without the builds changing +or the total karma going so low it is unpushed, +it will be pushed stable automatically. + +There are defaults for these thresholds +which vary at different points in the release process. + +If you choose to use the karma auto-push threshold, +please carefully consider an appropriate feedback level. +For a relatively obscure package which is quite stable, +1 or 2 may be an appropriate value. +For a popular, sensitive and complex package +such as `firefox` or `kernel`, +the default may be insufficient +and a choice of 5 +or even 10 +may be appropriate. + [#handling_feedback_from_automated_tests] == Handling feedback from automated tests