DeveloperWiki:How to be a packager

Follow package guidelines

Package guidelines can be found in the Arch Linux documentation, follow them closely.

Preparation and setup

Installing the packages

Make sure you have the packages devtools and namcap installed.

SSH configuration

If you have multiple SSH keys in your SSH Agent, you will need to make sure that the correct key is being used to contact the Arch servers. Also, when your local username differs from the one being used on the Arch servers, you need to take care of that too.

Example ~/.ssh/config excerpt:

Host repos.archlinux.org
	User archie
	IdentityFile ~/.ssh/id_arch
	IdentitiesOnly yes

Also make sure to set your ssh key in Gitlab:

Host gitlab.archlinux.org
	User git
	IdentityFile ~/.ssh/id_arch
	IdentitiesOnly yes

Tip: While you are at it you can also add your packager GPG key to show the "verified" tag on your signatures on Gitlab. For more information about this see [1].

makepkg configuration

Make sure to configure your ~/.makepkg.conf with the correct PACKAGER and GPGKEY variables. Wrong signatures or missing PACKAGER will prevent your packages from entering the repository.

PACKAGER="Archie <archie@archlinux.org>"
GPGKEY="0x0123456789abcdef"

Helper scripts (optional)

The packaged helper scripts below can be installed from the archlinux-tools group.

arch-rebuild-order — List the rebuild order of packages using the local pacman syncdb's.
arch-signoff — Signoff packages from testing interactively in your terminal.
arch-repro-status — List the reproducible status of your packages interactively in your terminal with the ability to see the build logs and diffoscope output per un-reproducible package.
archlinux-contrib — Collection of contrib scripts used in Arch Linux.

The workflow

Checkout/update a local package repository

Checkout an existing package:

$ pkgctl repo clone packagename

Tip: This clones over SSH by default so if you do not have a GitLab account you need to clone over HTTPS by specifying the --protocol argument: pkgctl repo clone --protocol=https.

Update an existing, previously checked out, package:

$ cd packagename
$ git pull

Adding a new package

This step is only required when adding a new package to the repository for the first time.

$ pkgctl repo create --clone new-package
$ cd new-package
$ cp /usr/share/pacman/PKGBUILD.proto PKGBUILD
$ $EDITOR PKGBUILD
$ $EDITOR .nvchecker.toml
$ git add .

Tip: pkgctl version setup will attempt to create the .nvchecker.toml configuration file automatically by analyzing the source array specified in the PKGBUILD.

Warning: dbscripts does not support packages with a different split package architecture.

Change and build

It is mandatory to build your package using a clean chroot. pkgctl build does this automatically.

$ pkgctl build --edit some-package

Run namcap on both PKGBUILD and package

Note: When using pkgctl build, this is done automatically.

$ namcap PKGBUILD
$ namcap some-package-1.0-1-x86_64.pkg.tar.zst

Run checkpkg on the package

Note: When using pkgctl build, this is done automatically.

Run in the directory with your freshly built package to get a file list diff compared with the package version currently in the repositories.

$ checkpkg

Note: This can be skipped when adding a new package to the repository for the first time (e.g. by importing it from AUR to extra).

Run sogrep on identified soname change

Note: When using pkgctl build, this is done automatically.

If checkpkg identified a shared object name (aka. soname) change in package's library package.so, it is required to rebuild packages directly depending on it.

To identify which packages rely on a given library in package in the main stable repositories (i.e. core and extra), use sogrep (see sogrep(1)).

$ for repo in core extra; do for lib in $(find-libprovides package | sed 's/=.*//g'); do sogrep -r $repo $lib; done; done | sort | uniq

Build package for its respective staging environment (by following the remaining steps in the workflow) and create a TODO with the identified dependents, so their maintainers can rebuild them against the new version of package.

Note: First sync with Package Maintainers and/or developers, if any packages currently in the staging environment block the rebuilds against package.

Use devtools to sign, upload and commit

Once you are satisfied with the package, you need to make sure all your changes are tracked in the repository. Run:

$ git status

in the some-package directory and check the output carefully. If, for example, you have added a new some-package.install file, you need to tell git to track that file, e.g.:

$ git add some-package.install

Make sure to never add the binary packages, makepkg logs, etc. to the repository!

When you are ready to proceed, you can run the devtools scripts to sign, upload and commit your work:

$ pkgctl release --message "update to 1.2.3, add post_upgrade hook to fix permissions"

Please try to write concise commit messages. If the package is simply an upstream change, that is fine, but if anything more complex changes, please inform us by writing an appropriate commit message.

Warning: Make sure to also specify --testing when releasing if you built against testing. Otherwise the package could be linked against dependencies that are not present on the target system.

This will upload the package and its signature to their repository specific location in your user's ~/staging directory on repos.archlinux.org aswell as creating a signed tag for the version on the packages git repository.

Update the repository

Using db-update will find new packages for a set of repositories, depending on which is being called.

To release uploaded packages to core, extra, gnome-unstable, kde-unstable, staging, or core-testing and extra-testing use:

$ pkgctl db update

Other operations

Removing a package

Using pkgctl db remove will remove a package from a specific binary repository.

To remove a package from any of the Official repositories use:

$ pkgctl db remove reponame libfoo

Moving a package between repositories

Using db-move will move a package between two binary repositories.

To move packages of the same pkgbase between core, extra, gnome-unstable, kde-unstable, staging, or core-testing and extra-testing, use:

$ pkgctl db move source_repository target_repository pkgbase...

e.g. to move packages of the pkgbases foo and bar from core-testing to core:

$ pkgctl db move core-testing core foo bar

Miscellaneous stuff

Avoid having to enter your password all the time

When working with pkgctl and the other devtools, quite a few ssh connections are established. For some setup this means that even when using ssh keys and the ssh agent that you have to unlock keys or need hardware tokens multiple times. You can work around that as follows:

Add this to your ~/.ssh/config:

Host gitlab.archlinux.org
    ControlMaster auto
    ControlPath /run/user/%i/ssh-%r@%h:%p
    ControlPersist 15m

Enter your password and leave that session open until you are finished. All ssh sessions to Gitlab will now be tunneled through this connection.

Troubleshooting

Pushing to the wrong repository

If you find yourself accidentally having pushed a package to the wrong repository (e.g. running pkgctl release with --testing instead of --staging against example-1.0.0-any.pkg.tar.zst) you can undo it.

Note: This only applies to cases where the repository update has not been done yet. If the repository has been updated already, refer to #Moving a package between repositories.

Remove the package from the staging location on the repositories server:

$ ssh repos.archlinux.org "rm staging/extra/example-1.0.0-any.pkg.tar.zst*"

Afterwards, proceed again with signing, uploading and committing.