Difference between revisions of "Talk:AUR submission guidelines"

From ArchWiki
Jump to navigation Jump to search
(Improvements from the AUR page that was reverted: re, move proposals to #Proposals and close it)
m (Improvements from the AUR page that was reverted: fix link)
Line 4: Line 4:
 
If you'd like to see how this page should look, and get a history without other changes, I've made a [[User:Quequotion/AUR submission guidelines|full page draft]]. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 09:55, 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 [[User:Quequotion/AUR submission guidelines|full page draft]]. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 09:55, 11 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:AUR]] (and the following mass adoption of content without prior consensus). Closing the subsections below ([[#Proposals]]) hence.
+
: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.
  
 
== <s>Proposals</s> ==
 
== <s>Proposals</s> ==

Revision as of 13:16, 11 June 2019

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)

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.

Proposals

Proposal: Submitting packages

Warning: Before attempting to submit a package you are expected to familiarize yourself with Arch packaging standards and all the articles under "Related articles". Verify carefully that what you are uploading is correct. Packages that violate the rules may be deleted without warning.

If you are unsure in any way about a package or the build/submission process even after reading this section twice, submit the PKGBUILD for review.

Rules of submission

When submitting a package to the AUR, observe the following rules:

  • Submitted PKGBUILDs must be in compliance with the licensing terms of the content to be packaged. In cases where it is mentioned that "you may not link" to downloads, i.e. contents that are not redistributable, you may only use the file name itself as the source. This means and requires that users already have the restricted source in the build directory prior to building the package. When in doubt, ask.
  • Submitted PKGBUILDs must not duplicate applications in any of the official repositories. Check the official package database; if the package exists, do not submit a duplicate. If the official package is out-of-date, flag it as such. If the official package is broken, or lacking a standard feature, please file a bug report.
The only exception to this is for packages with extra features enabled and/or patches in comparison to the official ones, in which case pkgbase should be different to express that. For example, a package for GNU screen containing the sidebar patch could be named screen-sidebar. Additionally the provides=('screen') array should be used in order to avoid conflicts with the official package.
  • Do not create duplicate packages. Check the AUR if the package already exists. If it is currently maintained, changes can be submitted in a comment for the maintainer's attention. If it is unmaintained or the maintainer is unresponsive, the package can be adopted and updated as required.
  • 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.
The AUR and official repositories are intended for packages which install generally software and software-related content, including one or more of the following: executable(s); config file(s); online or offline documentation for specific software or the Arch Linux distribution as a whole; media intended to be used directly by software.
  • Do not use replaces unless the package has been renamed or deprecates another, for example when Ethereal became Wireshark. If the package is an alternate version of an existing package, use conflicts (and provides when the offending package has dependents).
Note: replaces forces pacman to install the replacement package as an upgrade of the offending package, while conflicts tells pacman to remove the offending package only if the conflicting package is to be installed.
  • Add a comment line to the top of the PKGBUILD file which contains information about the current maintainers and previous contributors, respecting the following format. Remember to disguise your email to protect against spam. Additional or unneeded lines are facultative.
If you are assuming the role of maintainer for an existing PKGBUILD, add your name to the top like this:
# Maintainer: Your Name <address at domain dot tld>
If there were previous maintainers, list them as contributors. The same applies for the original submitter if this is not you. If you are a co-maintainer, add the names of the other current maintainers as well.
# Maintainer: Your name <address at domain dot tld>
# Maintainer: Other maintainer's name <address at domain dot tld>
# Contributor: Previous maintainer's name <address at domain dot tld>
# Contributor: Original submitter's name <address at domain dot tld>

Proposal: Verifying packages

Comment: Splitting this section in half between the maintainer-oriented parts and user-oriented parts, which will remain on the Arch User Repository page. quequotion (talk) 04:42, 11 June 2019 (UTC)
  • To avoid problems caused by your particular system configuration, build packages in a clean chroot. If the build process still fails in a clean chroot, there is proabably an issue with the PKGBUILD.

Authentication

Comment: No changes to propose for this section.

Creating or adopting package repositories

If you are creating a new package from scratch, or adopting an orphaned package, establish a local Git repository and an AUR remote by cloning the intended pkgbase. If the package does not yet exist, the following warning is expected:

$ git clone ssh://aur@aur.archlinux.org/pkgbase.git
Cloning into 'pkgbase'...
warning: You appear to have cloned an empty repository.
Checking connectivity... done.
Note: The repository will not be empty if pkgbase matches a deleted package.

If you already have a package, initialize it as a Git repository if it isn't one, and add an AUR remote:

$ git remote add label ssh://aur@aur.archlinux.org/pkgbase.git

Then fetch this remote to initialize it in the AUR.

Note: Pull and rebase to resolve conflicts if pkgbase matches a deleted package.

Publishing new package content

Warning: Your commits will be authored with your global Git name and email address. It is very difficult to change commits after pushing them (FS#45425). If you want to push to the AUR under different credentials, you can change them per package with git config user.name "..." and git config user.email "...".

To upload or update a package add at least PKGBUILD and .SRCINFO then any new or modified .install files, patches or other local source files; commit with a meaningful commit message, and finally push the changes to the AUR.

Tip: To keep the working directory and commits as clean as possible, create a gitignore(5) that excludes all files and force-add files as needed.

For example:

$ makepkg --printsrcinfo > .SRCINFO
$ git add -f PKGBUILD .SRCINFO
$ git commit -m "useful commit message"
$ git push
Note:
  • After modifying a package, except for very minor changes (such as fixing a typo) that would not require re-installation of the package, update its version accordingly.
  • Regenerate .SRCINFO after updating such PKGBUILD metadata in order to publish it in the AUR.
  • If .SRCINFO was not added before your first commit, add it by rebasing with --root or filtering the tree so the AUR will permit your initial push.

Proposal: Maintaining packages

  • Check for feedback and comments from other users and try to incorporate any improvements they suggest; consider it a learning process!
  • 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.
  • 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.
  • Additional maintainers can be added to or removed from a package by clicking "Manage Co-Maintainers" under "Package Actions" on the right of its AUR page and editing the list.
  • If you do not want to continue to maintain the package for some reason, disown the package by clicking "Disown package" under "Package Actions" on the right of its AUR page 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.
  • Orphaned packages can be adopted by clicking on the "Adopt Package" link under "Package Actions" on the right of its AUR page.

Proposal: Other requests

Deletion, merge, and orphan requests can be created by clicking on the "Submit Request" link under "Package Actions" on the right hand side. This will send a notification email to the current maintainer and to the aur-requests mailing list for discussion. A Trusted User will then either accept or reject the request.

Deletion

You may request to unlist a pkgbase from the AUR. A short note explaining the reason for deletion is required, as well as supporting details (like when a package is provided by another package, if you are the maintainer yourself, it is renamed and the original owner agreed, etc).

Note:
  • It is not sufficient to explain why a package is up for deletion only in its comments because as soon as a TU takes action, the only place where such information can be obtained is the aur-requests mailing list.
  • Deletion requests can be rejected, in which case if you are the maintainer you will likely be advised to disown the package to allow adoption by another maintainer.
Comment: I have heard this is one of the bits of content in dispute that led to the reversion of the AUR, although it is not my creation, which you may observe by its cargo culting onto this new page. Perhaps the latter part should be removed or reworded such as: "in which case you should disown the package (and perhaps flag it out of date); unwanted, disused packages are eventually purged." quequotion (talk) 10:32, 11 June 2019 (UTC)
  • After a package is "deleted", its git repository remains available for cloning.
Merge

You may request to delete a pkgbase and transfer its votes and comments to another pkgbase. The name of the package to merge into is required.

Note: This has nothing to do with 'git merge' or GitLab's merge requests.
Orphan

You may request that a pkgbase be disowned. These requests will be granted after two weeks if the current maintainer did not react.

Proposal: Promoting packages to the community repository

When AUR packages receive enough community interest and the support of a Trusted User, they may be adopted into the community repository (maintained by the TUs), from which binary packages can be installed using pacman.

Usually, at least 10 votes are required for something to move into community. However, if a TU wants to support a package, it will often be found in the repository.

Sufficient votes are not the only requirement; there has to be a TU willing to maintain the package. TUs are not required to adopt a package even if it has thousands of votes.

Usually, when a very popular package stays in the AUR it is because:

  • Arch Linux already has another version of a package in the repositories.
  • Its license prohibits redistribution.
  • It helps retrieve user-submitted PKGBUILDs (AUR helpers).

See also Rules for Packages Entering the community Repo.