Talk:AUR submission guidelines

Improvements from the AUR page that was reverted

It was in grievous error that this page was created from the version of the AUR page that it was reverted to, and not the version that it was reverted from. Not only has it made this content more difficult to navigate, but left the AUR page in a broken state with maintainer-oriented FAQs, etc that now have no place there. Several issues with the page that had been discussed and resolved have been restored to a broken state as well (which forum should users or maintainers use; policy on packages shipping binaries, etc). quequotion (talk) 04:42, 11 June 2019 (UTC)

If you'd like to see how this page should look, and get a history without other changes, I've made a full page draft. quequotion (talk) 09:55, 11 June 2019 (UTC)

There are a lot of changes to review; so I've compiled a rundown of them on the talk page of the draft. quequotion (talk) 13:48, 14 June 2019 (UTC)

Please keep the draft on the User:Quequotion/AUR submission guidelines. Using this talk page for three purposes - article discussion, draft, and draft discussion - makes it extremely hard to follow, as made obvious by the stalling discussions in Talk:Arch User Repository and the following mass adoption of content without prior consensus. Closing the subsections below (#Proposals) hence. -- Alad (talk) 13:16, 11 June 2019 (UTC)

I'd like to post a reminder that these proposals still stand. If anyone in a position to review the changes and comment, or implement them, feels overwhelmed: I ask you to consider that you are making it hard on yourself. Pick any one section of the breakdown, read the reasons I give for the changes I have made, follow the link at the end of the section to see the specific changes, leave a comment. Each section--including the specific changes--should only take a few minutes to read. There's no need to go through the whole set of proposals at once. Start somewhere, please. The page needs these changes. quequotion (talk) 15:47, 5 January 2021 (UTC)

Nobody is making it hard on themselves, merely we are volounteers and don't have the time to review a complete overhaul of one of the most central articles in the wiki. Since people complained about the protection status, though, I am wondering if you still plan on going ahead and push your changes at will, given the opportunity, or wait for consensus like any other wiki editor. -- Alad (talk) 22:00, 13 January 2022 (UTC)

I have always been willing to get consensus. In almost every case, and remember the initial effort was dozens of small edits and never monolithic, I attempted to start a discussion before making changes. In some cases, I had that discussion in IRC and proceeded with what I perceived as approval from Trusted Users; I now understand that only discussions on talk pages "count". In some cases, I waited several months to make relatively trivial changes and then made them anyway; I got into a habit of asking for approval, waiting for someone to say no, and going ahead when it became clear that no one was interested in addressing the issues. I understand that a lack of disapproval is not equivalent to approval, just as I did then, but we need to address the facts that most changes to the wiki are made without discussion at all, proposals can languish on talk pages for years before someone realizes they are worth talking about, and the only way to actually start the discussion is often to have one's changes reverted. This workflow needs improvement even more than this page.

I understand that everyone is a volunteer, so am I. I am willing to do the work if anyone is willing to engage. I didn't propose or make these changes just to satisfy my vanity, and I won't say I am right about everything, but these changes are an earnest attempt to help not only readers of this wiki but the Archlinux project as a whole. I would love to discuss each and every proposed change, get your input, and make improvements wherever possible. We can do it in any order you like, and any time you like, if you (or any one else who's consent is sufficient) are ready to talk about them. quequotion (talk) 10:13, 14 January 2022 (UTC)

Considering most TUs are inactive on the wiki, maybe you could improve your chances at review by using the new "RFC" process: [1]

Note that an RFC needs at least one developer or TU that supports it. I'm not TU anymore, so you should open a discussion first in [2] or some other place like aur-general. -- Alad (talk) 14:32, 15 January 2022 (UTC)

To note an alternative, you could also apply as TU. That way you're sure to reach the people you want to reach. This needs 2 sponsors and basic qualifications explained in Trusted User. -- Alad (talk) 14:40, 15 January 2022 (UTC)

I'd like to start moving forward. One change that would be very helpful for this page, as well as the AUR page, is to upgrade the bulleted list of requests that can be made on the AUR web interface into individual subsections. The benefit here is for navigation on this page (readers will be able to select a type of request they need to know more about from the table of contents) and navigation from the AUR page (where sections refrence one of the requests specifically, they will be able to link to it directly rather than the enitre "requests" subsection). Here is what that will look like. This small change will do a great deal of good for navigation and readability across two of the most critical pages in the wiki. Please respond. quequotion (talk) 14:25, 19 April 2022 (UTC)

It's short list of points, a transformation to a section with subsection and Notes seems a bit much. Someone skipping from the table of contents would only skip a few sentences, and knowing about 1 type of request without knowing of the other two is not that useful for AUR users. -- Alad (talk) 23:04, 19 April 2022 (UTC)

Thank you for your response. I understand it doesn't seem like much information to be concerned about how accesible it is, or how well it is organized. It is not the amount that warrants this, but the importance of the information. It will also be helpul for a link or two on the AUR page to navigate here. As you say, the content is not lengthy, skipping to a specific will not prohibit readers from discovering what is directly above or below it: people will still be able to learn about all the requests just as easily as they will be able to look up a particular one. The notes are warranted in part by text already in the section ("Note this...", "Note that...") and also to distinguish information that is not critical to making a request (such as that packages git repositories continue to exist after deletion delists them in the AUR) or that explains the reasons for requirements (such as the deletion request in the AUR mailing list being the only available record after the request is granted).

The goal here is for the page to be as readable as possible, and that includes fixing issues like having a bulleted list inside a bulleted list. The easier this text is to internalize, the fewer people will make mistakes for lack of having understood it or ask questions it should have already answered for them. There were also a number of fixes to the text itself in my original draft, but those can be saved for later if there is some debate to be had over them; I note there may also be new information since that draft was written which I will of course incorporate.

Keep in mind, now that we are no longer dealing with a protected page I can do the work. I would not offer to do it if it were not worth doing. Improving readability, in ways both big and small, is worth doing. quequotion (talk) 14:40, 20 April 2022 (UTC)

Explicit statement about source hosting in AUR

Sometimes users tend to include little scripts in the AUR package itself and not use external hosting. As far as I understand this is not welcome, but I could not find any source for that. I propose adding a statement to the rules making this rule clear (if it is indeed valid). Fordprefect (talk) 09:41, 4 June 2020 (UTC)

I know this post is 2.5 years old but I am still going to reply to it.

I believe there is currently no conventions, some people prefer to use scripts to automate the process (I believe this is discouraged but not prohibited), and some people choose to use a git platform such as github to help others contribute towards the PKGBUILD.

The AUR is a dumping ground of packages, you may come across a really good package in a pile of bad ones, its just the way it is!

PolarianDev (talk) 09:51, 13 March 2023 (UTC)

Explicit mention of hosting configuration files

Packages which only include configuration (files or commands) are usually not allowed on the AUR, because they are already documented on the wiki with the necessary context. This holds especially when the configuration is straightforward to use outside of a package, e.g. enabling a service or blacklisting a module. It can be seen as a specific version of:

Make sure the package you want to upload is useful. Will anyone else want to use this package? Is it extremely specialized? If more than a few people would find this package useful, it is appropriate for submission.

however, being more explicit does not hurt. Related discussion: [3] -- Alad (talk) 12:18, 4 May 2021 (UTC)

Sounds good to me.

-- NetSysFire (talk) 12:25, 4 May 2021 (UTC)

What about packages providing simple pacman hooks, systemd services, udev rules and similar things copy-pasted from the wiki? E.g. [4], [5], [6], [7].

What about [8]?

— Lahwaacz (talk) 07:49, 5 May 2021 (UTC)

I personally and very selfishly hope these are allowed to stay. While I could make those files myself, I really appreciate them being tracked by the package manager, especially in cases where they have dependencies on other packages (e.g., the dash hook wouldn’t work very well without dash installed), and it seems like a lot of wasted effort to make my own PKGBUILD for this knowing that others have already done this. —Freso (talk) 08:06, 5 May 2021 (UTC)

Make the method to create AUR remote more clear

Hello,

Today (2022-12-14 YY/MM/DD) I have been discussing how to create AUR packages on the remote over on the AUR mailing list. I found section 1.3 a little confusing.

Personally I believe I got confused due to the simplifications made, if it explicitly stated that "cloning a non existent repository will create the remote" and "pushing to a non-existent remote will automatically create it" it would be a little easier to understand, however on the other hand this could have just been me being bad at interpreting language.

I think the two workflows described on the 1.3 section are fine. If you creating something from scratch you follow the commands and clone a new empty repo (Users shouldn't care much that behind the scenes there's a repository created or not - it should be transparent to them). If you are editing a package same thing, clone the repo, make changes and commit/push.

Artafinde (talk) 13:22, 14 December 2022 (UTC)

I guess it is just me overcomplicating things, personally not having any real explanation of how it worked completely confused me, just adding commands doesn't really help in my opinion and just promotes people copying and pasting without any clue what is going on. But I guess this is an issue only I would have, or people who overcomplicate every problem, thus if nobody else wants to comment you are free to close this discussion.

PolarianDev (talk) 13:27, 14 December 2022 (UTC)

I think a mention of how technically works is useful but not to the average user. So instead of replacing the current text with a complicated explanation of how on the backend we use a git repo and split branches which would confuse a lot of people maybe just add a bit of explanation in addition to what's there already. :) Make a suggestion here.

Artafinde (talk) 13:32, 14 December 2022 (UTC)

I agree to some extend, maybe it is just best to extend the section and provide a more in-depth explanation on top of the current explanation, so that those who are interested (or people like me who ask too many questions) are able to find all the information required, this is a wiki, thus it should be aimed to provide information for all levels, whether beginner or someone who wants to know more into the subject. Personally I say extend the section, and those who aren't interested can just ignore it.

PolarianDev (talk) 13:58, 14 December 2022 (UTC)

I think it is also worth mentioning that the repository will not appear on the AUR web unless the .SRCINFO is pushed to the remote. Maybe linking to the wiki on how to automatically generating the .SRCINFO using the MAKEPKG file.

After clarification on the mailing list, it makes sense fully, but for whatever reason it completely confused this...

PolarianDev (talk) 11:33, 14 December 2022 (UTC) PolarianDev

I believe this is made clear by AUR submission guidelines#Publishing new package content; in fact, it's not supposed to let you push without a.SRCINFO (though I don't think anything prevents you from letting it get out of date). -- CodingKoopa (talk) 02:18, 19 December 2022 (UTC)

C0rn3j,

I saw this edit: Special:Diff/766802, and I thought maybe what would be better would be a more general "familiarize oneself with package creation, check for specific guidelines for the type of project to be packaged". Each guidelines page already says these things within their scope. quequotion (talk) 01:08, 7 February 2023 (UTC)

In my opinion, a rewrite of 1.1 would be best, from the current dense bulletpoints to header sections. In that setup, the three separate packaging bulletpoints could be put into a signel section. I would keep the examples for `package` `package-bin` and `package-git` and mention that specific things/languages have different prefix/suffix rules and link to https://wiki.archlinux.org/title/Category:Arch_package_guidelines for more information. C0rn3j (talk) 00:52, 9 February 2023 (UTC)

Automation and Package Maintenance

There has been a heated discussion on the aur-general mailing list about the question whether it is ok to use automation to deal with package maintenance and to which extend automation is accepted. I therefore propose to save the central outcomes of this discussion as a new sub-paragraph to Section 2 "Maintaining Packages" named something like "Use of Automation Tools for Package Maintenance".

The main contents of the section would be along the following lines:

• Package Maintenance is a process that may require manual intervention (this would be expanded on why that is)
• Automation is tolerated, as long as it fulfills the following:
  • packages are built in a clean chroot
  • packages are test-installed
  • The packages is checked for basic functionality (i.e. by running check())
  • changes to the PKGBUILD only get pushed if all previous steps are run successfully
• Automation tools should generally be used in combination with manual intervention (aka the CI creates the PR) for nontrivial packages
• Packages that do not adhere to this guidance may be subject of a deletion request (so the Author has some time to fix his setup) and authors are asked to stop using tools until fixed

Note that I dont take a strong stance on any of this, I just want to somewhat summarize the discussion!

Gromit (talk) 09:31, 15 April 2023 (UTC)

+1 from me. I have seen the discussion unroll and agree that we should explicitly document that our official policy is: automation is not a replacement for having a human maintaining packages, but a tool in their bag to speed up things.

Edit: I've tried to do a small draft, but I feel I'm being too verbose. --Erus Iluvatar (talk) 10:18, 15 April 2023 (UTC)

+1 for the idea, but I dislike the draft.

Instead of linking Jelle's email, we should add that to "See also", I feel it is important for us to clarify fully what the job en-tales, to make it more clear that you should be checking for new or outdated dependencies etc (they are listed within the mailing list discussion if you want to take a look).

I think it might be a good idea to remind people that contributing to the AUR is voluntary, they must have free time to give, and they can not replace their lack of time with CI/CD automation to try to maintain as many packages as they can. I am aware people desperately want to help out, just like me, but you need time to give, otherwise you are doing a dis-service (sorry for being harsh), it makes it harder for others to maintain a package which has a CI/CD task which keeps pushing untested, unverified updates to the AUR.

Anthraxx has stated in the mailing list[9] that you shouldn't be pushing automatically to the AUR, this is implied from his comment to another AUR maintainer.

I think there should be more empathsis on clean chroot builds before pushing. I see a lot of people not building in a clean chroot, which is the classic "it works on my system", I am not a TU (maybe one could back me up or correct me), but for my clean chroots I only install base-devel and any dependencies listed in the PKGBUILD (including makedepends), if it does not build then it is clear there is missing dependencies which have not been pulled in.

CI/CD packages have caused me a lot of trouble, so I have a natural bias against them, so I might be a little harsh with my recommendations, but what do others think?

PolarianDev (talk) 12:27, 17 April 2023 (UTC)

Thanks for the extensive answer, I'll try to reply by following its structure:

1/ Linking the relevant message by creating a new section in the page for it feels unnecessary and convoluted to me: the draft explicitly paraphrases Jelle's message with "e.g. projects can change license, add or remove dependencies, and other notable changes even for "minor" releases" and seems self-sufficient.

2/ I don't think this is the place to dictate how people should allot their time when contributing to our community, but only highlight the technical requirements for submitting packages to the AUR and maintaining them.

Maybe we should create a longer dedicated section regarding what updating existing packages entails.

3/ The linked message from Anthraxx simply states the two previous answers by Jelle and himself are an official stance from Arch Linux developers / packagers.

Jelle's message is:

I'd say automation is fine, if it opened a pull request which can be

reviewed and tested. But blindly pushing new versions to the AUR is for

me a no-go.

Anthraxx message is:

Taking the currently described state into account I would like to kindly

request that you stop and disable the automatic pushing. Bumping

packages without any testing and check() is not a good thing, even when

you try to revert afterwards.

The added emphasis is mine, as I read neither of those as explicitly forbidding automation for packages, as long as some precautions have been taken before the updated PKGBUILD is provided to AUR users.

It seems this is also the opinion of one of the answers before Jelle and Anthraxx joined:

[…]What's the difference between a

maintainer patching version and checksums, executing a clean build and

then pushing it and an automation doing the same? - Nothing.

An answer on the ML is making a good case for CI/CD pushing to the AUR after testing, as it can avoid human error for some tasks.

An other good example that has not already been brought up on the ML would be a developer pushing to the AUR when they have a new version available. In that case, the already know of any "upstream" change that has taken place, so automation at that step would also be appropriate.

4/ +1 from me to have more links to DeveloperWiki:Building in a clean chroot

5/ I will admit that I have no experience with CI/CD and the related automation, but I think I'm not too naïve in how I understand the subject, and I hope you've mostly been exposed to bad instances of it, as it seems to me that it's a helpful tool when properly set.

--Erus Iluvatar (talk) 14:00, 17 April 2023 (UTC)

I'm generally against the CI/CD of AUR packages. My stance is coming from issues I've seen with AURweb backend such as this one and the fact that most automated tools are broken and create wrong PKGBUILDs and / or packages. If we are going ahead with something on the Guidelines then I'd suggest to drop the "may" from points 1 and 4. Furthermore executing check() function in a PKGBUILD says nothing about if the package is functioning. At _best_ case it's just executing developer's written tests (at worst case it just returns 0 and exits the function) - but doesn't mean that the package is build properly and it's working when installed. It says nothing about runtime dependencies are correct, or as jelle said the Licences are in place etc. If one is not willing to build them manually and ensures the package is working then might as well skip the packaging. The false prestige of maintianing hundrends of packages in AURweb is a burden to Trusted Users having to maintain them (with requests) if most of them are broken. I think having statement about automated CI/CD like the above is a (https://dictionary.cambridge.org/dictionary/english/pandora-s-box Pandora box).

Artafinde (talk) 10:09, 7 May 2023 (UTC)

For the bot pushing with a broken email, we should explicitly address that separately, as right now the only mention of the email is in AUR submission guidelines#Publishing new package content which does not explain it will break our back-end.

Given that there are already people using automation, I'd say we should have a strong case to fully ban it, e.g. the previous ROS maintainer seems to have used automation without breaking stuff.

Is the new version of the draft more explicit in what's a hard requirement?

--Erus Iluvatar (talk) 10:47, 7 May 2023 (UTC)

Addressing the suggestion of validating emails are not broken, how exactly are we meant to do that, every time an AUR push occurs a user must verify their email? or only allow commits signed with the email which has been used by an AUR account?

If you do prevent non-AUR emails, then github CI/CD will break (unless a user resigns the commit and overwrites the changes, or another work around), and furthermore would promote the use of more accounts, which is strictly against the AUR guidelines, you can not have a second account as it, as put in the guidelines, has almost no use other than for malicious means (such as spam).

From the mailing list, and me looking around the AUR for packages, it seems there is a lot of CI/CD tasks on github pushing directly to the AUR, some of them not even checking the PKGBUILD works in a clean chroot before pushing. It seems like a nightmare for TUs right now, and considering some of them are for and some are against it is really hard to write up guidelines for the AUR without having more participation.

I suggest we either revive the current mailing list thread, or create a new one and get a more general point of view, not just the ArchWiki contributors, possibly even move it to arch-general and request a vote from the TUs on the issue?

In any case, this is too much of a hot potato right now to add into the page, and doing so could cause a lot of confusion, and you would also need to ease it into effect, give time for maintainers to make up their mind on what to do, whether to abide by the new guidelines, or orphan their packages. As highlighted by the thread so far, it seems CI/CD is used by people who do not have a lot of time, and thus, bringing this into effect could cause massive amounts of orphaned packages, it is NOT something we should be hasty, sorry gromit as I know you wanted to add the draft into the main page.

Anyone opposed bring this to Mailing List once again with the aim of more participation, and hopefully a call to vote from TUs?

PolarianDev (talk) 15:55, 7 May 2023 (UTC)

If I have understood the issue correctly, our back-end only dislikes unset emails, so it should be fine to simply say somewhere that pushing to the AUR requires an email to be set, nothing more.

I have no hard feeling on this issue, but I think it would indeed be best if the rules are agreed upon by TUs (be it through a vote, a participation on this topic or through the mailing list, I have no clue): they are the ones that have to handle the AUR afterwards, so they should be the ones to decide on this.

I fully agree that we should wait until a clear consensus emerges, AFAIK this subject has not been contentious in the ~8 years since the migration to AUR4 happened, many people have had time to pick up "bad" habits that they might have to change now.

--Erus Iluvatar (talk) 16:34, 7 May 2023 (UTC)

Draft

• Check for feedback and comments from other users and try to incorporate any improvements they suggest; consider it a learning process!
• Please do not leave a comment containing the version number every time you update the package. This keeps the comment section usable for valuable content mentioned above.
• Please do not just submit and forget about packages! It is the maintainer's job to maintain the package by checking for updates and improving the PKGBUILD.
• If you do not want to continue to maintain the package for some reason, disown the package using the AUR web interface and/or post a message to the AUR Mailing List. If all maintainers of an AUR package disown it, it will become an "orphaned" package.
• Automation is a valuable tool for maintainers, but it can not replace manual intervention (e.g. projects can change license, add or remove dependencies, and other notable changes even for "minor" releases). Automated PKGBUILD updates should preferably take the form of a merge request on a maintainer's own repository to be manually approved, and run a minimum of verification steps, that is any automation:
  • must verify the new PKGBUILD successfully creates a package in a clean chroot,
  • must verify the resulting package installs,
  • must check the generated binaries will run,
  • should execute the check() function if provided by upstream,
  • should verify the output of Namcap,
  • should test basic functionality on the generated binaries.