User talk:Quequotion/AUR submission guidelines
Breakdown of changes
I've been told my changes are hard to follow, and this--in part--led to the reversion of several months' work on the AUR page and splitting half of it into a protected page. I will try here to describe the changes as best I can. Nonetheless, if you are looking to compare the draft to the current page that is what you should do; rather than digging through edit histories, compare the two at their current state (just like you would two drafts of a physical document), and leave feedback from this comparison.
As some changes depend on others, this breakdown will be in the order such changes are intended to be made.
- That is not to say they couldn't be done in any order. We can discuss each change piecemeal, which is the purpose of this commentary. For example, the new sections ("Promoting packages to the community repository" and "Verifying packages") should probably be the first changes applied. quequotion (talk) 07:53, 10 July 2020 (UTC)
Publishing new package content
The tip regarding gitignore(5) is located at the bottom of this section; so it is likely that first-time readers will miss it when pushing their package repository. This belongs closer to the section where a user is told how to create a repository, and backed up by use of git add -f in the example.
Another change here was to relegate several points of advice that are not necessarily required parts of the process into a Template:Note.
Finally, the instructions about adding and committing could be more optimally worded.
This was done in four sequential edits, starting here.
Requests
First of all, it would be logical to list the requests in the same order as they appear on the AUR Web Interface.
This section is a long bulleted list with another bulleted list within it; it could really use a facelift. Giving each request its own subsection would also be handy for other sections of the page to link to.
Since the reversion, I've been told the statement regarding rejection of package deletion requests is in dispute; we should do something about that.
See how I tried to work this out the first time, over six sequential edits, starting here.
- Splitting the "Requests" content into subsections saved me from doing this edit (linked to #Deletion), but I still have to fix the link in this discussion. quequotion (talk) 00:23, 18 June 2019 (UTC)
- I think seeing is believing. I've gone ahead and made the changes despite the lack of enthusasim. Nothing has been lost: all current links to "Requests" will still go there. There are a couple of pages that could link to a specific type of request instead; will consider those changes later if this one sticks. quequotion (talk) 13:46, 6 January 2023 (UTC)
Promoting packages to the community repository
- Arch User Repository#Voting for packages is in, making do by not linking "in that process" to anywhere for the time being. quequotion (talk) 11:15, 11 July 2020 (UTC)
There are two FAQs with information about getting packages into the community repository, as well as it being mentioned along side voting for packages in various places in the article.
To reduce the search time users face trying to get all the information together, this section merges all of one FAQ with some of the information from another FAQ.
This was done in three sequential edits, starting here; note that the second edit is actually to link "Voting for packages" to this section.
Since the reversion, it has been brought to my attention that "packages in source format" is a more controversial terminology than I had considered. I have since reworded the remaining "What is the difference between the Arch User Repository and the community repository?" FAQ, which resulted in further reduction as a bonus.
Verifying packages
Package verifying and debugging information is scattered across both pages. Although such information can be found by reading Creating packages, Makepkg, PKGBUILD, and DeveloperWiki:Building in a clean chroot, some of the information is AUR-specific (such as which forums to ask for help in, linking to IRC, etc).
Most of the information comes from Arch User Repository#Foo in the AUR does not compile when I run makepkg; what should I do?, Arch User Repository#I have a PKGBUILD I would like to submit; can someone check it to see if there are any errors? and the header of AUR submission guidelines#Submitting packages. Combining these sections allowed for several simplifications in addition to taking advantage of existing tutorials in other articles and linking to them rather than duplicating them on these pages.
This was done in six sequential edits, with some error in execution of the fourth (content was copied from the "Submitting packages" header but not deleted there with other simultaneous changes occurring), starting from here.
- To reduce the wall-of-text effect, some parts of this section were elevated to bullet points in a later edit.
Rules of submission
First and foremost, in addition to the "Rules of submission" section, there's an FAQ that contains an additional rule of submission--and an important one at that. This is in regard to license compliance; given the copyright climate since the DCMA, this should be given a prominent place in the "Rules of submission", as was done over two sequential edits from here.
The style in which several of the rules are written is not effective. Some use too much bold text, which is more distracting than educational; others say "Please.." or "Please do not..", which implies that they are not rules but suggestions that may be ignored. The explanation of replaces and conflicts is probably too technical. Rules should be firm and easy to internalize. I made several edits to simplify and make these rules more effective.
Regarding duplication of official repository packages, packages that ship binary blobs (a partial reversion of Polyzen's -bin edit), duplication of AUR packages (which had it's rule listed after its explanation), listing package maintainers (does not need to say please), replaces and conflicts (over three sequential edits).
- Other, non-sequential, edits were made to this section, such as this, which attempts to apply Help:Style and also links "Check the AUR" to User:Quequotion/Arch User Repository#Getting Started, which explains about searching the AUR, and "comment line" to a man page, which explains bash comments. This is followed by more non-sequential style edits, Special:Diff/573736 and Special:Diff/573738.
- Something I've been considering for a while is combining the two bullet points about duplicate packages, as they are essentially the same point. quequotion (talk) 12:43, 21 July 2019 (UTC)
Maintaining packages
The bullet point regarding disowning a package recommends to use the AUR Web Interface but does not describe how to use it. Although it makes for more to read, I thought this would be a good addition.
Two of these guidelines say "Please". These appear to be rules, and if they are to be followed it is not necessary for them to ask to be followed. See Special:Diff/574476.
Adopting orphaned packages is mentioned a few times on the page, but how to do so is not documented. I attempted to do this here and here. I was incorrect about the necessity of adopting a package through the AUR Web Interface before pushing; as I have been told it is indeed possible to adopt simply by pushing to an orphaned repository over ssh. This still ought to be documented.
Adding co-maintainers is another undocumented feature of the AUR. I documented it here.
- I've added some details regarding orphaned packages, namely to reiterate the policy of waiting two weeks for a maintainer to respond before filing an orphan request and noting that pushing content to an orphaned repository adopts it. quequotion (talk) 13:21, 21 July 2019 (UTC)