Re: How can we improve the Changes Process?

On 6/28/26 22:21, Maxwell G wrote:
> Hi everyone,
> 
> I've been thinking about the Changes Process recently and how we can 
> improve it for Change Owners, Change Wranglers, FESCo members, and 
> participants in Change discussion and feedback. I'm not officially 
> proposing to change anything now, but I wanted to put some ideas out 
> there and see how people feel about this or if anybody has other ideas/ 
> thoughts/opinions.
> 
> ---
> 
> Any changes to the Changes Process should go through the Changes Process 
> or a similar community feedback process.
> 
> We need to be aware of other processes/teams/scripts that consume 
> Changes so that they can be adjusted accordingly.
> 
> The policy should encourage requesting unofficial "pre-feedback" on the 
> devel list before writing or submitting an official proposal for large- 
> scale or potentially controversial/disruptive Changes. This happens 
> sometimes right now but not always, and I think some Changes could 
> benefit from this optional extra step.
> 
> We should move away from the Wiki and wikitext formatting. Wikitext is 
> yet another text markup format that we use in Fedora that is not 
> familiar to everyone, and it's apparently hard to parse 
> programmatically. We could consider storing metadata about Changes (such 
> as targeted release, change owners, status, FESCo issue number) in a 
> structured way using Markdown front-matter that tools that work with 
> Changes can easily consume.
> 
> Changes should be written in markdown, or a markup format that can be 
> easily converted to markdown or bbcode for display on Discourse, and 
> also for plain text emails. If we use asciidoc, that would allow us to 
> publish approved Changes to docs.fedoraproject.org which might be nice.
> 
> We should store Changes as text files in a git repository. Change owners 
> would propose Changes by filing a PR against the repository and then the 
> Change would be announced after the Change Wrangler reviews and merges 
> the Change text. We could have CI checks to validate Changes (e.g., to 
> make sure that system-wide Changes have the correct optional fields) and 
> various other opportunities for automation that we don't have with the 
> wiki.
> 
> Discourse should _not_ be the primary source of truth for Change 
> Proposal texts. I've heard suggestions to use it for this, since it's 
> one place and already supports markdown-formatted text and is currently 
> used for discussion, but I don't believe it's a good place to store and 
> work with Changes. There's not a good way to programmatically access 
> Changes if they were stored in Discourse. Forum software is not meant 
> for archiving anything. A repository of plain text files is better- 
> suited for this purpose.

I think "primary source" and "archiving" are different use cases.

I fully agree that Git repo with changes in a readable text format would 
be the best possible archiving solution.

--

Personally I like the OpenStack approach to design specs. See example in:

https://specs.openstack.org/openstack/nova-specs/readme.html
https://specs.openstack.org/openstack/nova-specs/specs/juno/template.html

It has Git review workflow, CI, static site generated for the merged 
content, specs are moved from ./approved/ to ./implemented/ when done.

--

But Discourse _can_ be a possible entry point to start and handle the 
Change Discussion.

Discourse does store all posts in markdown-like form and keeps history 
of changes.

You can access the markdown version of any post via 
/raw/<thread-id>/<message-number> link, like
https://discussion.fedoraproject.org/raw/144297/1

And all previous revisions can also be accessed programmatically with 
some additional privileges

https://meta.discourse.org/t/how-to-get-a-previous-version-revision-of-a-post-through-the-api/58164


Thus, since Discourse already handles authentication, formatting, 
rendering, notifications,.. it might be cheaper to use Discourse as the 
"web-form" to create a change, and then use the markdown versions of it 
for next processing steps, which would include creation of a PR in the 
Git repo, adding necessary metadata and whatever else needed to it.

You could do things like: have the preliminary discussion of a Change 
Proposal by creating the Change thread on Discourse, but then "promote" 
that thread to the next step by exporting the text description of a 
change from the thread into the Git PR.

> 
> This part doesn't have to go along with a migration away from the Wiki 
> that I am suggesting, but I wanted to float the idea here. I think we 
> should consider whether to stop announcing Changes on Discourse. Cross- 
> posting to Discourse was proposed as an experiment in fesco#2989, but 
> there was never a decision made about whether to stop or continue with 
> the experiment. I find the fractured discussions between devel@ and 
> Discourse hard to follow. I think the Discourse setup makes it easier 
> for discussions to "accelerate" or become toxic or repetitive. I don't 
> think it's any better at handling large threads.
> 
> All the best,
> Maxwell

P.S.

No matter what you choose in the end, removing the wiki syntax step from 
the process would already be a huge improvement. And maybe instead of 
designing the whole new workflow, we should focus on "what would be the 
minimal possible change to the existing process which would achieve that.


-- 
Aleksandra Fedorova
Matrix: @bookwar:fedora.im
Fediverse/Mastodon: @[email protected]
-- 
_______________________________________________
devel mailing list -- [email protected]
To unsubscribe send an email to [email protected]
Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/[email protected]
Do not reply to spam, report it: https://forge.fedoraproject.org/infra/tickets/issues/new