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
