Move distribution guidelines to a Git repo

This sounds like a good idea to me. Wiki discussion pages are a nightmare to follow and sometimes never have real resolution.

I would suggest a Markdown based format with an eye to it being published on a specific distro guidelines site (using an SSG like zola or mdbook generated docs site) to make browsing and linking to the guidelines more pleasurable than mucking around it GitLab.

The one downside I see is that many good contributions to packaging issues come from regular AUR contributors that will be cut off, but hopefully the GitLab instance does eventually get opened up to the public so interested contributors can be part of the process again.

I would also suggest this be somewhat broadened to include the DevWiki pages. There is quite of overlap in there related to packaging, but most of it is more dated than the public Wiki on the same topics and it's frustrating as a new TU trying to figure out what the "actual" guidelines are. Currently the public Wiki pages are too fluid and uncoordinated, while the dev wiki pages are full of broken windows because there is no way to fix them up open to the parties encountering the brokenness. This proposal to start a distro guidelines repository managed via GitLab strikes a nice middle ground between these two extremes.

First, this appears to be about the Arch package guidelines, so I suggest this RFC to be renamed accordingly. If you want to rename things, it should be discussed rather than implied. If you want to move other guidelines as well, we need a precise list of pages this RFC applies to, so that we know what we are talking about.

Some further comments:

Motivation

Having the guidelines in this format fuments lack of discussion, as there is no review process enforced.

I don't know what this means, since fuments does not appear to be an English word.

Lastly, the discussion process (via the wiki talk page) is not very friendly, which has surely demotivated/stopped people from contributing to the discussions.

What do you mean by this? Do you have some specific examples? If this is mainly about the lack of response, I don't see how moving the content to git (or anywhere else) would help. Even the "Drawbacks" section admits that git sets a higher bar for contributions...

Drawbacks

IMO the RFC dives into technical solutions based on arguments like "we hate MediaWiki" (indeed we do!) which apply to the wiki as a whole, not only to the guidelines. It would result in the fragmentation of our documentation in many places and it does not address the topic of content quality. If these arguments win, we should migrate the whole wiki off MediaWiki, but that is obviously a completely different discussion...

Also @alad said (on IRC, obviously): but wherever you put it, it doesn't change the fact that these are guidelines and nobody follows them

Alternatives considered

We could add a review process to the guidelines and still keep them in the Arch Wiki

Protecting the pages on the wiki is just a matter of several clicks. Of course, it should still be discussed.

though I believe moving then to a Git repo is just easier.

Moving the content is the easy (and idempotent) part. You would also need to convert the text to a different format (Markdown is assumed so far), set up rendering (Gitlab), and other things I did not think about. Though I think discussion will be still the most time consuming part, so asymptotically both solutions have the same complexity...

Have there actually been any documented cases of abuse stemming from the openness of the Wiki?

https://wiki.archlinux.org/index.php?title=Talk:Rust_package_guidelines&curid=28910&diff=691627&oldid=587853

Looks like wiki discussions on packaging guidelines do actually work...

As one of the two parties involved in that discussion, allow me to register my objection to that being used as a positive example. The Wiki discussion page is a royal pain in the the behind: I've lost blocks of text to edit clobbers twice, missed things @grawlinson wrote multiple times, had to reformat the whole thing to make sense of it multiple times, and at the end of the day there are two new TUs going back and forth with little mechanism for resolution. By contrast this RFC discussion is way more effective. Being able to propose a change before doing it, revise it along the way, comment on specific lines of a proposed change, resolve threads, thread at all... the list goes on.

That kind of stuff is an objection to mediawiki though. That's part of a bigger problem, even the wiki staff doesn't like the platform (as lahwaacz pointed out already).

Raising the bar to contribute package guidelines by moving them (which ones? still hasn't been pointed out by anyone) to a git repo, which can only be written to by staff, is tangential to that.

I'm not a super fan of mediawiki but I don't see issues with the Packaging Guideline pages being of low quality, what pages do you think have low quality or are now inconsistent?

There are "issues" with the DeveloperWiki pages being a bit stale and containing a ton of old irrelevant stuff, but that's not the packaging guidelines.

Alternatively, is there a way to improve the current discussion system within mediawiki using plugin/addon?

https://www.mediawiki.org/wiki/Extension:StructuredDiscussions might be an option.

https://www.mediawiki.org/wiki/Help:Structured_Discussions/Quick_tour

changed this line in version 3 of the diff

This makes it a lot harder to contribute a new packaging guideline for, for example zig. Currently someone who is a domain expert can create a Packaging page which can later be improved by the Arch Linux packager in the repositories. An RFC process would raise the bar immensely and by limiting approval by Arch staff, they would become gatekeepers of progress.

What makes the whole arch staff team (ops,bbs moderators for example) an expert for said packaging guidelines?

I wouldn't consider tips starting to collect for a new language without current guidelines to be a substantial change to core guidelines and hence could be done by anybody without an RFC process. In fact I'd probably just nuke the RFC bit from this proposal entirely, I can't think of any case where an RFC workflow would be better than just a PR workflow. Needing a dev or TU to merge is a lot lower bar but still protects against nonsense. PRs that generate discussion can and will naturally get more review.

I think the RFC bit is fine. For changes that affect core packaging guidelines, it is clear we need an RFC. Needing an RFC if someone suggests one also covers a contributor being unsure about whether a proposed change is in that scope.

I'm still waiting for someone to point out which wiki pages "had nonsense added" because of supposedly no review occuring.

changed this line in version 3 of the diff

I never had any issues with the guidelines pages on the wiki. To be honest, I don't see the need for this RFC. If we had the guidelines pages constantly vandalized to a point where it would affect someone's packaging, then it would've been something else.

Indeed. Since 2015, there were precisely 2 cases of controversial edits to guidelines (VCS package and AUR submission), which were 1. reverted immediately and 2. resulted in the respective pages being locked for editing.

This RFC on the other hand gives the impression ArchWiki is some kind of wild west where nobody reviewis anything. Claiming that is already rude, refusing to back up the claim, and using it as an excuse to remove Arch users from content and discussions, is much more so.

This RFC on the other hand gives the impression ArchWiki is some kind of wild west where nobody reviewis anything. Claiming that is already rude, refusing to back up the claim, and using it as an excuse to remove Arch users from content and discussions, is much more so.

I have been slow to respond as I am honestly overwhelmed (not necessarily because of this, just this in addition to everything else in my life). Since many people seem to be personally invested in this, I wanted to take time to write a reply where I state my beliefs, opinion, and POV on this in a clear and straightforward way, so that people don't misinterpret it like they are doing the motivation section of the RFC. To be clear, I am at fault here because the motivation section is not well written, however, putting words in my mouth and claiming they are rude is not in any way a constructive contribution to this discussion, it honestly only demotivates me further. So, I will take some time to reply and rewrite the RFC, but I recommend you take a step back and re-evaluate your approach to this discussion.

To be more specific, I was talking about this clause of the RFC:

"Having the guidelines in this format fuments lack of discussion, as there is no review process enforced. Review is solely based on people watching the wiki page and noticing changes. This results in low-quality and inconsistent guidelines."

(emphasis mine) as well as that our GitLab does not allow user registrations, such that the proposed model is limited to staff members - as discussed above.

My comment about rudeness stemmed from my impression that wiki maintainers would not do their job. It however did not fit in well with the rest of the discussion and was too aggressive, sorry about that.

Anyway, it would definitely be appreciated if issues and questions raised here can be addressed.

To add a concrete suggestion, I would make an RFC to move the:

1. Arch package guidelines
2. AUR submission guidelines

to git, because changes to these require consensus across packagers and TUs, respectively.

Other than that, one might move the few remaining (active) pages on DeveloperWiki. I see no benefit in moving other pages. i.e. other package guidelines are domain-specific and edited by perhaps 1 or 2 packagers, as discussed previously.

I'm not a fan of moving some parts to Git, it makes it harder to find as some information is on the wiki and some of it on Gitlab. I hope the proposal creator realises how much the wiki benefits our distribution and if there is something to improve to start a constructive, friendly conversation with the wiki admins/contributors.

I'm in favor of the move as I had a hard time about "guidelines" (from the wiki team) about how to modify a package guideline on git which just didn't make sense. And MRs are designed to be changes that can easily be reviewed by adding comments to line which is harder in the wiki.

As for splitting the information: We can still provide pages on the wiki that link to the guideline repository or even think about taking the written markdown of these documents and convert them with some tool (like pandoc) to HTML or something.

I don't have anything against mediawiki, but I feel that the process of changing such documents feels more natural here in gitlab.

I think the big advantage here would be the inherent review process associated with the new workflow as opposed to just kinda changing it. Then again, usually we only have one or two experts for every ecosystem so the review might not be too much of a benefit? Unsure about this one.

Yes, typically packaging guidelines for specific languages/domains are written by the 1 or 2 people who are both knowledgeable on the topic at hand and willing to write about it.

I should also add that for larger changes or new content, it is common to first make a draft on your user page and have it reviewed before moving it to the main namespace on the wiki. See it as a kind of "merge request" that takes a minimal amount of self-discipline.

The fact that I have to make a draft on my page and then get it reviewed means also that people have to manually compare them. In gitlab the review process is by default a diff and makes the review easier.

Also I had issues with the wiki team imposing certain rules of how to edit the document claiming that they have to make sure that no false data gets added to the page. With defining specific reviewers to the process we move the load from the wiki people and also have reviewers in place who know the ecosystem of the language guidelines which are being changed.

With defining specific reviewers to the process we move the load from the wiki people and also have reviewers in place who know the ecosystem of the language guidelines which are being changed.

That's just wishful thinking. Why would people who have rarely (if ever) edited the guidelines suddenly become more involved if the guidelines were to be moved to GitLab?

I'm talking about once reviewers which know the ecosystem are in place. One idea we talked about during FOSDEM is that the maintainers of the main language package (ruby, rust, go, ...) will be the reviewers. And they are the one who deal with packages for this language and that language on a much more higher frequency that someone on the wiki team.

And what prevents them from reviewing changes to the guidelines while they're in the wiki? While it's after-the-fact reviewing, no one has proved that has caused any issue so far.

I had the issue that I had approval of the people who knew how ruby packaging works and we agreed on the change but I then had a huge discussion with the wiki team about HOW i have to edit the wiki page to make small changes and so on which from the context of the guidelines document doesn't make sense. And I think this doesn't make sense to enforce from my point of view "random" rules and the argument was because the wiki team needs to make sure that no wrong information was added. That would imply that the entire wiki team knows how packaging works in order to be able to review this. It would be less of a hustle if the wiki team would see who edited the page and trusts the change and not doubting legitimate arch staff member edits.

added 1 commit

• 1a5891bc - rfc0005: update based on feedback

Compare with previous version

Sorry for the delay, I pushed a significant update with the following changes:

• Limit scope to the packaging and AUR submission guidelines
• Motivation section rewritten
• The specification now specifies the review rules
  • Reviewing changes
  • Adding and removing code owners
  • Review disputes (as last resort)
• Removed the RFC process request
  • Explicitly notes this isn't a replacement for the RFC process
  • Asking for an RFC is now just part of the review process
    • Maintainers can request the proposal goes through an RFC before merging
    • Disputes are handled the same as other changes

I think it now should be better, please let me know if you still have issues with the current version.

The new version looks good to me and I would be happy to see it move ahead.

added 14 commits

• 1a5891bc...36ec95b8 - 12 commits from branch archlinux:master
• a182609f - rfc0005: initial version
• ab200a05 - rfc0005: update based on feedback

Compare with previous version

added 1 commit

• 2edd2896 - rfc0005: update based on feedback

Compare with previous version

Friendly ping. There were a couple of people looking forward to a resolution on this RFC, so please let me know if there's anything else I need to do.

Sorry, even so I still head the mails in my inbox to remind me, somehow this topic got a bit lost on my side. I know I was the one pushing you to rewrite it and I thank you. I think it is a great idea to go forward with this. Thanks for the ping.

No worries, I took a longer to get this done anyway . I just wanted to make sure I was not missing anything blocking the RFC.

There is an error in the CI pipeline which seems to come from an update of the tool used and some command line flag not being understood anymore. I guess it would make sense to create an issue out of it and resolve this in a dedicated MR?

+1 to all these suggestions

How does this work when e.g. three are against the removal and two for the removal?

There are a few typos, etc. to fix.

Other than that I like the more narrow approach that the RFC has now.

FWIW, I'd be happy to see something of a "handbook" for Arch Linux (distribution) maintainers in the future, of which the packaging and AUR submission guidelines would be a subset.

I know this RFC has been open for quite a while, but would you be interested in considering the angle of a "handbook", which describes "how to run the distribution" (in contrast to information on "how to use the distribution" for which I believe the Arch Wiki to be the ideal place) for it? Currently, I don't have much more than e.g. archlinux-keyring and pkgctl (i.e. "how to be a packager") use in mind for that.

mentioned in merge request !21 (merged)

The discussion here is stalled and the proposed RFC was superseeded by MR !21 (merged).

closed