Well, "Bodhi enablement" can't be dropped exactly, though we should probably rename it. There is still a big difference between Rawhide-and-early-Branched "immediate automatic stable push as long as gating checks pass" mode and the mode we enter shortly after Branching where karma or time requirements are enforced. That's what is currently referred to as the "Bodhi enablement point". Suggestions for new names on a postcard. :)

.-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-.
|                                                           .-------.   |
|                                                           |       |   |
|    Dear Fedora,                                           |       |   |
|                                                           |   50¢ |   |
|                                                           |       |   |
|             I propose the term:                           `-------'   |
|                                                                       |
|                                                                       |
|                                                                       |
|                         "Updates testing enablement"                  |
|                                                                       |
|                                                                       |
|      Sincerely,                                                       |
|      Miro                                                             |
|                                                                       |
|      PS This is supposed to be a postcard                             |
|                                                                       |
|                                                                       |
`-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-'

(Edited to add the stamp.)

Not a post card, but FWIW the schedule now calls it "Bodhi updates-testing activation point" after receiving similar feedback from Adam and/or Mohan. (Mohadam?)

When one updated package requires another (or more than one other)

Maybe "When one updated package requires on or more other packages" ? I think that'd be more natural than the version with a parenthetical clarification.

Maybe split the (source) text one-sentence-per-line?

• link:https://docs.fedoraproject.org/en-US/rawhide-gating/multi-builds/[Rawhide Gating/multi-builds]

"." should be here, and not after HOWTO] above.

Try not to push a broken build

Pushing broken builds was considered "semi-ok" in the past, and hence this recommendation is so weak.
We should make it much stronger:

Never push a broken build

And "SHOULD" above could be changed to "MUST".

All updates MUST be ready for consumption in the Fedora release their bodhi update is created for.

This may be read as that packagers must not submit updates unless they are 100% sure about them (esp. with "MUST").
Maybe:

Bodhi updates should be created only for packages which are expected to qualify for being pushed to stable.
Maintainers should not create bodhi updates for test or other builds that they never intend to push stable.
This sort of testing should be done in link:https://copr.fedorainfracloud.org/[Copr] or other seperate public repositories.

Also:

Consult with the QA team for further testing assistance.

I'm not sure. Can the QA team realistically help, except in isolated cases? Most of the testing is done by contributors who are not part of the official "QA team".

It's intended that this tree meets

"This tree is intended to meet" ?

As soon as a build is completed, a bodhi update is automatically created and the update is used to
show test results. If gating tests pass, the update is marked stable after a few minutes, pushed stable
and will be added to the next nightly compose.

I'm looking at e.g. https://englishstudyonline.org/fanboys/, and the uses of "and" here seem to fall into the "coordinate two or more items", which would mean that some commas are missing.

I think this would read better as:

As soon as a build is completed, a bodhi update is automatically created.
The update is used to show test results.
If gating tests pass, the update is marked stable after a few minutes, pushed stable, and will be added to the next nightly compose.

This is to prevent others from being able to depend on changes once they have happened.

"This is required to allow others to depend on the build once it has become visible."

In exceptional cases, releng may untag packages, but this will be a last resort.

Unnecessary repeat. Maybe just "In exceptional cases, releng may untag packages."

automatically created when a build finishes, tests run and automatically pushed to include in the next

"automatically created when a build finishes, tests run, and builds are automatically pushed to the next"

(or "into the next compose")

until there is a successfull

"until there has been a successful" (note typo fix)

(below)

"(see below)" ?

have indicated that some of these tests block release

Unless I'm misunderstanding what this is about, this should be something like "have marked the tests as blocking"

FESCo will work with QA and others to prevent or mitigate the issue.

This sentence repeats what is in the previous paragraph.

When one updated package requires another (or more than one other)

Maybe "When one updated package requires on or more other packages" ? I think that'd be more natural than the version with a parenthetical clarification.

Maybe split the (source) text one-sentence-per-line?

Agreed. Done.

• link:https://docs.fedoraproject.org/en-US/rawhide-gating/multi-builds/[Rawhide Gating/multi-builds]

"." should be here, and not after HOWTO] above.

Fixed.

Try not to push a broken build

Pushing broken builds was considered "semi-ok" in the past, and hence this recommendation is so weak.
We should make it much stronger:

Never push a broken build

And "SHOULD" above could be changed to "MUST".

ok. How about "Never push a known broken build" ?

All updates MUST be ready for consumption in the Fedora release their bodhi update is created for.

This may be read as that packagers must not submit updates unless they are 100% sure about them (esp. with "MUST").
Maybe:

Bodhi updates should be created only for packages which are expected to qualify for being pushed to stable.
Maintainers should not create bodhi updates for test or other builds that they never intend to push stable.
This sort of testing should be done in link:https://copr.fedorainfracloud.org/[Copr] or other seperate public repositories.

How about:
Bodhi updates should only be created for builds which are expected to qualify for being pushed to stable.

Also:

Consult with the QA team for further testing assistance.

I'm not sure. Can the QA team realistically help, except in isolated cases? Most of the testing is done by contributors who are not part of the official "QA team".

Well, I was picturing some base package wanting special testing before being officially built. I think the QA folks could indeed advise how to test it and call for testers.
But perhaps we should make sure they want this in there before we include it. @adamwill ?

It's intended that this tree meets

"This tree is intended to meet" ?

Changed.

As soon as a build is completed, a bodhi update is automatically created and the update is used to
show test results. If gating tests pass, the update is marked stable after a few minutes, pushed stable
and will be added to the next nightly compose.

I'm looking at e.g. https://englishstudyonline.org/fanboys/, and the uses of "and" here seem to fall into the "coordinate two or more items", which would mean that some commas are missing.

I think this would read better as:

As soon as a build is completed, a bodhi update is automatically created.
The update is used to show test results.
If gating tests pass, the update is marked stable after a few minutes, pushed stable, and will be added to the next nightly compose.

Changed.

This is to prevent others from being able to depend on changes once they have happened.

"This is required to allow others to depend on the build once it has become visible."

In exceptional cases, releng may untag packages, but this will be a last resort.

Unnecessary repeat. Maybe just "In exceptional cases, releng may untag packages."

Changed.

automatically created when a build finishes, tests run and automatically pushed to include in the next

"automatically created when a build finishes, tests run, and builds are automatically pushed to the next"

(or "into the next compose")

Changed.

until there is a successfull

"until there has been a successful" (note typo fix)

Changed.

(below)

"(see below)" ?

Changed.

have indicated that some of these tests block release

Unless I'm misunderstanding what this is about, this should be something like "have marked the tests as blocking"

Changed.

FESCo will work with QA and others to prevent or mitigate the issue.

This sentence repeats what is in the previous paragraph.

Yep. Dropped.

Will push these changes as another commit (and can squash them at the end when we are ok with them).

I think this should be renamed to something like "from post-branch-freeze to bodhi-change-point" as there's no freeze period and to avoid confusion with beta-freeze

Why "beta-freeze"? Isn't that at the end of Pre Beta period?
What about "Bodhi compose enablement point"?

I think this should be renamed to something like "from post-branch-freeze to bodhi-change-point" as there's no freeze period and to avoid confusion with beta-freeze

Well, its 'pre' the beta freeze, but I guess I can see how someone might confuse that with another freeze... it's hard to describe it without describing it in relation to a thing thats a freeze. :(
Will try post-branch-freeze-to-bodhi-change-point. Thanks.

Why "beta-freeze"? Isn't that at the end of Pre Beta period?

No, it's the beginning of the pre-beta period...

What about "Bodhi compose enablement point"?

ok, adjusted. Another commit will be pushed in a min.

Thanks for comments, keep em coming!

Why call it "bodhi compose enablement"? I find that is even less descriptive than "updates-testing enablement point". I think it will be probably confusing to anybody who is not familiar with how the internal processes work (and does not care whether a release is composed by bodhi or koji at any point in time).

The only thing that changes for packagers is that they need to create updates manually instead of them being created automatically, so why not call by how it affects packagers: the point in time after which bodhi updates need to be crated manually by packagers instead of automatically? Maybe ... "Switch to manual update creation" , "Start of manual update flow", or even "Termination point of automatic bodhi update creation"?

Yeah, I know, at this point this sounds like "I like my bikeshed green" ... but especially for new contributors, descriptive language matters a lot, and exposing implementation details, like which process is used to "compose" builds into a repository, is more confusing than helpful, in my experience.

Why call it "bodhi compose enablement"?

I have to concur. The title is "beta-freeze and bodhi-compose-enablement", but the text talks about neither of the two. I agree with @decathorpe that the primary way how we refer to this phase should be based on how users (i.e. our packagers) view this. There should also be a separate paragraph that describes that in this phase the way that composes are done is changed.

These freezes are technically not a part of the Updates Policy, but are briefly mentioned here for clarity. The link:https://fedoraproject.org/wiki/Milestone_freezes[Milestone freezes] page provides more details and is the canonical reference in case of any conflict.

IIRC, this text was written by @adamwill ages ago. I don't think it makes sense anymore. This document describes the freezes in detail as an integral part of the update policy. So I think it'd be better to just say something like
"link:https://fedoraproject.org/wiki/Milestone_freezes[Milestone freezes] describes the processes of submitting packages as freeze exceptions."

--

Re: the detailed description of karma requirements for packages.
1. Are those descriptions even correct? https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/PQNU6ODOGNYLEASNHMN72TJGBJ6PWDEM/ says they are not ;( @decathorpe comment please.
2. Do we want those detailed descriptions? We have very verbose and repeated descriptions of critpath and the minimum karma requirements, and then we say that packagers must create updates, and only in a footnote clarify that effectively this is all enforced by bodhi. (A text like "From this point onward Maintainers MUST Push all updates first to updates-testing." is actively harmful, because it confuses packers by telling them to do something which they can't actually do and what is done automatically.)

I think we should completely invert the text:
- in the main text, just say "Updates must be created in bodhi. Minimum karma requirements for updates are specified in the table below. Bodhi sets reasonable defaults and enforces those requirements for updates."
- add a table where the reqs are listed. I think this will be much easier to grok than the repeated descriptions in prose. (Obviously the table must match what bodhi actually implements...)

The text does not describe automatic pushing of updates. The table should make a distinction between when bodhi will automatically push an update to stable and when the maintainer is allowed to manually push the update to stable.

Re: the detailed description of karma requirements for packages.
1. Are those descriptions even correct? https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/PQNU6ODOGNYLEASNHMN72TJGBJ6PWDEM/ says they are not ;( @decathorpe comment please.

Yeah, this is really confusing, because there are multiple avenues for packages to get submitted for "stable", and the values are different for critpath packages. So unless I am remembering something wrong, these are the ways to make update go "stable":

non-critpath updates:

• update reaches "autokarma" (minimum +1, default value +3)
• update is unpushed if it reaches "negative autokarma" (default value -3)
• update reaches "autotime" (minimum 7 days, default value 7 days - unless when applied to a branched release between "bodhi updates-testing enablement point" and "beta freeze", then both those values are 3 days)
• update reaches "minimum stable karma" and packager pushes it to stable manually before it reaches the set "autokarma" or "autotime" values

critpath / EPEL updates:

• update reaches "autokarma" (minimum +2, default value +3)
• update is unpushed if it reaches "negative autokarma" (default value -3)
• update reaches "autotime" (minimum 14 days, default value 14 days, unsure how this value is different between updates-testing enablement and beta freeze)
• update reaches "minimum stable karma" and packager pushes it to stable manually before it reaches the set "autokarma" or "autotime" values

Both the automatic "stable" pushes by bodhi for "autokarma" and "autotime" only happen if the respective option is enabled for the update (on by default).

The "minimum stable karma" seems to be +2 regardless of critpath / EPEL status, but this doesn't seem to be documented anywhere.

This is, to the best of my knowledge, the "complete linearized decision tree for updates going to stable" . If I made a mistake, please correct me. Maybe @mattia can help us out here.

This is, to the best of my knowledge, the "complete linearized decision tree for updates going to stable" . If I made a mistake, please correct me. Maybe @mattia can help us out here.

A quick graph of the requirements needed for pushing an update to stable are summarized here. This is what the draft says, then I checked in Bodhi and it seems correct to me.

For non-critpath updates we only have a requirement of 3 or 7 days in testing, but that can easily be overridden by the submitter setting a min karma to +1, so that as soon as the updates get a positive karma, it will be autopushed to stable.

Would someone want to propose a PR/commit on top of this one? I am afraid I am finding it hard to fold in most recent round of comments. You want a table for all the ways packages go stable?

I'm fine changing bodhi-compose-enablement, but I don't like any of the proposed new names...

I think things might be getting a bit unwieldy here. Originally this doc was for maintainers to know what to do... but now it seems like it's turning into a comprehensive doc on how the updates work with composes and how the fedora lifecycle works. Perhaps it should be split into 2 docs? one just for what maintainers should know/do and one with more details on how everything works with composes, etc?

+1 'bodhi-compose-enablement' is a bad name for this policy. If we want a new 'generic' name that can be used for various docs aimed at various people, "full Beta requirement activation point"? Otherwise I kind of like @decathorpe 's suggestion of using a name relating to what packagers actually have to do, submit updates manually, for this document and others aimed at packagers.

These freezes are technically not a part of the Updates Policy, but are briefly mentioned here for clarity. The link:https://fedoraproject.org/wiki/Milestone_freezes[Milestone freezes] page provides more details and is the canonical reference in case of any conflict.

IIRC, this text was written by @adamwill ages ago. I don't think it makes sense anymore. This document describes the freezes in detail as an integral part of the update policy. So I think it'd be better to just say something like
"link:https://fedoraproject.org/wiki/Milestone_freezes[Milestone freezes] describes the processes of submitting packages as freeze exceptions."

I disagree. The Milestone freezes page is still the actual definition of that policy/process, and contains plenty of detail that this policy (as it stands, and after this PR) does not. It also doesn't really "describe the process of submitting packages as freeze exceptions" - it just links to https://fedoraproject.org/wiki/QA:SOP_freeze_exception_bug_process for that, which is the document that actually does that. The Milestone freezes page documents the whole of what a 'freeze' is and what it applies to and what that means. We could change "briefly mentioned" to just "mentioned" or "referred to", though.

Two more commits on top in #41, PTAL.