Difference between revisions of "User talk:Quequotion/AUR submission guidelines"

From ArchWiki
Jump to navigation Jump to search
(→‎Maintaining packages: : describe changes and additions to this section)
(→‎Other requests: delete extra 'an')
Line 19: Line 19:
 
First of all, it would be logical to list the requests in the same order as they appear on the AUR Web Interface.
 
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 an ''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.
+
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 [[Special:Diff/575133|that]].
 
Since the reversion, I've been told the statement regarding rejection of package deletion requests is in dispute; we should do something about [[Special:Diff/575133|that]].

Revision as of 09:22, 15 June 2019

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.

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.

Other 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.

Promoting packages to the community repository

Note: From this point on, the changes become more interdependent and their order more critical. This new section, for example, becomes mutually linked to User:Quequotion/Arch User Repository#Voting for packages as they relate to each other.

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

Note: With the package maintainer-oriented and user-oriented parts of the page split in across two pages, so this section needs to be split. See User:Quequotion/Arch User Repository#Debugging packages for the user-oriented content.

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, several 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.

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.