Talk:AUR submission guidelines

From ArchWiki
Latest comment: 23 May by Andrei Korshikov in topic C0rn3j,

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)Reply[reply]

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)Reply[reply]

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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]

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)Reply[reply]

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)Reply[reply]

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)Reply[reply]

Sounds good to me.
-- NetSysFire (talk) 12:25, 4 May 2021 (UTC)Reply[reply]
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)Reply[reply]
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)Reply[reply]

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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]

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) PolarianDevReply[reply]

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)Reply[reply]

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)Reply[reply]


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)Reply[reply]
So, what would be the structure?
(a) Usefulness and non-existence (here are the first three bullet points)
(b) Naming (here are bullet points with -git, -bin and "no suffix")
(c) PKGBUILD
By the way, I don't think that the text itself should be rewritten, just reorganized from flat list to structure. Bullets could become paragraphs, at least for some sections. Andrei Korshikov (talk) 00:24, 23 May 2024 (UTC)Reply[reply]
I see your point, but agree with @C0rn3j edition, and believe that these things are important enough to be repeated. -- Andrei Korshikov (talk) 00:26, 23 May 2024 (UTC)Reply[reply]

Described how to migrate git history when doing a "merge request"

Hi! I had to rename one of the AUR packages that I maintain recently. It turns out there's no direct process for doing this and it's a little complicated.

It's a two step process, combining migration of git history with a merge request.

I added a section on how to migrate git history for those who may not be as familiar with the AUR or git.

Please let me know your thoughts on this. It's my first significant contribution to a wiki :)

(Also it's late at night where I am, so my grammar might not be the best...)

EDIT: Here is the diff: Special:Diff/782013/next

Techcable (talk) 12:17, 29 June 2023 (UTC) TechcableReply[reply]

This does not belong to the guidelines page. I'll move your text to this talk page until a better place is found. Maybe Arch User Repository#Frequently asked questions? — Lahwaacz (talk) 10:38, 2 July 2023 (UTC)Reply[reply]

Migrating Git History

One use of merge requests is to rename an AUR package to an new name. This requires migrating git history before asking a TU to do a merge request. This is because a merge request only works if the destination package exists.

If the name of the destination package has never been used before, this may be as simple as pushing the commits to the new repository. This will implicitly create the destination package, along with copying the commits.

If a destination package has ever existed with the name you are migrating too, its old git history will still be there. This should be the case even if the package appears deleted in the web UI.

The AUR does not allow destructive git history operations or force-pushing, so you will need to graft the new history on top of the old one. This can be done using git merge with the merge strategy --strategy=ours. This will discard the file contents of the old history and override it completely with your own. After "merging" your new history on top of the old history, the AUR will finally allow you to git push into the destination repository.

$ git remote add aur-migrate-dest ssh://aur@aur.archlinux.org/target-name.git
$ git remote fetch aur-migrate-dest

Now actually create the merge commit, grafting our history on top of `aur-migrate-dest/master`

$ git merge --strategy=ours --allow-unrelated-history aur-migrate-dest/master

Push the merged history to the AUR. This is allowed because technically non-destructive (even though it overrides the old file contents).

$ git push aur-migrate-dest master

Note that the merge commit exists just for the purposes of preserving history from both repositories. It doesn't modify the contents of the repository. Unlike git rebase, this preserves the commit ids from the source repository in addition to the commit ids from the old repository. This is useful if you refer to commit ids within commit messages or code (git revert does this automatically).

After migrating the history, you are ready to submit the "merge request" to a Trusted User.

Note: When migrating package history, make sure you update `PKGBUILD` and `.SRCINFO` to reflect the changed names

Java packages and -bin suffix in package names

Current there is a rule about packages using prebuilts and -bin suffix

  • Packages that use prebuilt deliverables, when the sources are available, must use the -bin suffix. An exception to this is with Java. The AUR should not contain the binary tarball created by makepkg, nor should it contain the filelist.

It's unclear about Java packages. Literally, there is no rule about whether such Java packages should use a package name with -bin suffix or not. I propose to require the -bin suffix for new Java package using prebuilt binaries while allow existing packages without the -bin suffix (i.e., no need to submit deletion/merge requests for them).

A modified rule can be:

  • Packages that use prebuilt deliverables, when the sources are available, must use the -bin suffix. An exception to this is with Java, where new Java packages using prebuilt binaries must use the -bin suffix, while existing such packages without the -bin suffix are allowed. The AUR should not contain the binary tarball created by makepkg, nor should it contain the filelist.

There are some related discussions at https://lists.archlinux.org/archives/list/aur-general@lists.archlinux.org/thread/NTDTI3THTZNBHR7OKRXQB3NAROFN4OLM/. Any opinions?

—This unsigned comment is by Yan12125 (talk) 06:31, 5 August 2023 (UTC). Please sign your posts with ~~~~!Reply[reply]

@Yan12125 What is the current state of the proposal? Just hangs?..
(In my opinion — I see and appreciate the logic, but I'm just ordinary user…)
@Andreymal "(all it needs is just the time zone)" — Thank you!!! Now I know how to resurrect the "Reply" button. Thank you indeed. Andrei Korshikov (talk) 23:26, 22 May 2024 (UTC)Reply[reply]
By the way, I have a bit easier to read suggestion:
  • Packages that use prebuilt deliverables, when the sources are available, must use the -bin suffix. The AUR should not contain the binary tarball created by makepkg, nor should it contain the filelist.
So, yes, just remove that strange Java exception. The idea is coming from this Toolybird comment, i.e. these are guidelines, so that should not forcing to rename existing packages but on the flip side of the coin, the subsection is called "Rules…". Andrei Korshikov (talk) 00:01, 23 May 2024 (UTC)Reply[reply]