# Introduction

Behold, ~~winter~~ Git is coming. We've been working on and off to get Git packaging sources ready for a while now. Today I'd like to outline the final proposal regarding the action plan, workflow, tooling and also the reason for a couple of decisions. Consider this as a late xmas gift to our distro 🎁😻

# Timeline

We started with a proof-of-concept from Foxboron and are now closing in with a bunch of production ready changes finished by me in various components such as dbscripts, devtools, svn2git - including the great help of several other contributors related to infrastructure, repo converter and other components.

The current plan is to finally get all this rolled out around end of January or most likely right after FOSDEM 2023 where we could hack together on the last outstanding bits. Shortly, we'll also notify a couple of downstream projects so they can prepare themselves. After finishing all followup tasks and feedback loops, we'll communicate the exact migration window. Please look at the Roadmap item for more detailed steps.

The plan for the migration window is to have multiple people from different areas block time for a full weekend and start with the rollout on Friday. This would give us the freedom and flexibility to handle all kind of unforeseen issues that may pop up during the rollout. Throughout the main rollout phase, packaging would be shut down completely and packagers will need to update their devtools and local checkouts.

# Roadmap

The Git packaging sources will be the very first item on our future Roadmap. We'll soon see more cleanup and Epics on our Roadmap for all the bigger changes and improvements we want to prioritize and outline for our distro. The overall idea is to greatly increase transparency, have a better way to visualize and track progress, dependencies as well as action items.

https://gitlab.archlinux.org/groups/archlinux/-/epics/7

As I only started this Epic while we were already near the finish line, it mainly consists of a couple of condensed issues with sub-tasks in dependent projects such as infrastructure, dbscripts, devtools, as well as a list of general tasks tied to the Epic. In the future we want to utilize it better by breaking it down into sub-issues in a very early stage. However, the currently available Epic should be a good starting ground that everyone can subscribe to and comment on.

# Git repo layout

Lets get technical. The Git repo layout is related to RFC-14 (Merge package repositories) and most of its aspects were discussed during that proposal. However, let's summarize what that actually means for the packaging repositories and how all this looks like.

Every `pkgbase` will have its own dedicated repository that is stored in a single combined GitLab group called `packages` (e.g. https://gitlab.archlinux.org/archlinux/packaging/packages/foo). This allows us to have a well structured and simple layout, which provides the grounds for a per `pkgbase` issue board on GitLab (note: dealing with the issue boards is not part of the migration). Package maintainers will receive write access to the entire GitLab group.

Whenever we completely remove a `pkgbase` from our distro, we will archive the corresponding GitLab repository instead of deleting it. Being able to physically delete the GitLab repository would effectively circumvent force-push and tag protection rules. On top, preserving an auditable history of former packaging sources is actually a good thing.

# Git tag format

Because of Git tag format limitations (man `git-check-ref-format`), we convert certain characters such as `~` to dots `.` and the epoch delimiter will be a simple dash `-`. All Git tags are expected to be signed using valid packager keys available in archlinux-keyring. Some example pkgver with their matching Git tags:

- 1.0-1 ➡ 1.0-1 - 2:1.0-1 ➡ 2-1.0-1 - 1.0~rc2 ➡ 1.0.rc2

# dbscripts

The way dbscripts currently works will be simplified: Instead of having two separate checkouts for `packages` and `community`, we will instead only have a single dbscripts instance on repos.archlinux.org managing all packages.

https://gitlab.archlinux.org/archlinux/dbscripts/-/merge_requests/37

ACLs will be done on the application level using checks against Unix groups, as described in RFC-14. Once we rolled out the Git migration, we will have `junior-packager` and `junior-dev` Unix groups available for limited interaction with testing/staging repositories.

https://gitlab.archlinux.org/archlinux/rfcs/-/blob/master/rfcs/0014-merge-pa...

The current state of the pacman repository will not be stored alongside the `PKGBUILD` anymore as we did with svn (the `repos` directory next to `trunk`). Instead we will use a single state repository, that will keep track of all the information and mapping between git-tags, hashes and repositories. The canonical source of the state repository is repos.archlinux.org and will be mirrored by our GitLab. This way we keep it very simple and get rid of any kind of exfiltrate secrets lying around on repos.archlinux.org just to be able to push directly to GitLab.

For consistency checks, dbscripts maintains and updates read-only clones of all packaging source repositories. To reduce cache miss and transfer times, the infra will perform scheduled cache warming. This will be fast enough for most everyday usage. To further speed up huge rebuild sets like haskell or openssl, where this will be noticeable, we may add some complexity to dbscripts in the future that uses parallel with some smart error handling.

Any interaction with scripts such as `db-update` will be globally available in `$PATH`. However, interaction that requires to ssh into repos.archlinux.org (or setup local aliases) will be superseded by the new `pkgctl` tooling (more on `pkgctl` in the following sections).

# devtools

To handle new functionality (e.g. package source repository management, GitLab authentication, etc.) a new unified tooling named `pkgctl` has been created. The old scripts such as `commitpkg` have been reworked into a smarter and more convenient unified interface (the old scripts will remain available for a while). As packagers will need to adapt workflows for Git anyway, now was the best time so everyone only needs to adapt once.

https://gitlab.archlinux.org/archlinux/devtools/-/merge_requests/126

## repo management

The command `pkgctl repo` will provide a couple of functions to work with our package source repositories.

First and foremost the `clone` subcommand allows to conveniently clone and configure a package source repository from our GitLab:

pkgctl repo clone libfoo

It is also possible to clone all packages of a maintainer for convenient initial setup and a dedicated flag for mass edits:

pkgctl repo clone --maintainer yourlovelynickname

To clone a read-only checkout without a valid ssh setup, simply pass `--unprivileged` to the command:

pkgctl repo clone --unprivileged libfoo

Cloning will implicitly call the `repo configure` subcommand, which sets up some git repo settings and author information read from `makepkg.conf`. This for example ensures we use our archlinux identities for packaging even if another one is configured globally. This setup is also important as we will enforce git release tags to be signed by trusted keyring keys.

To re-configure existing clones, a simple wildcard can be used in the repo's root directory:

pkgctl repo configure *

Use the `repo create` subcommand to create a new repository in GitLab. Due to GitLab limitations, this requires to setup a valid auth token (more about it in the next section):

pkgctl repo create linux-is-awesome

## authentication

Certain subcommands such as `repo create` require a valid GitLab token which can be managed with the `auth` command. To let the CLI guide you through the creation and setup:

pkgctl auth login

To verify the current token and its validity:

pkgctl auth status

This will save the token in `${XDG_CONFIG_DIR}/devtools/gitlab.conf`.

## package release

This is one of the workflow steps that will get dramatically smarter and supersedes the `commitpkg` (which is usually used through symlinks such as `communitypkg`) and the `archrelease` scripts, while providing more convenient dbscripts interaction. The commitpkg/archrelease scripts will remain available for now, but should be considered a deprecated interface available during a transition period.

The `pkgctl release` command unifies the steps to commit, tag and upload build artifacts. It stages modified version controlled files for commit, creates a Git tag matching the `pkgver` and finally uploads all build artifacts.

Before trying to create a new Git tag, the tooling will ensure that the local clone is up-to-date. This should avoid inconsistencies when a package maintainer tries to upgrade and locally tag an already released version.

By default the target binary package repository will be auto-detected by querying the repo it is currently released in. When initially adding a new package to the repositories, the target repo must be specified manually. By passing either the `--testing` or `--staging` option, the matching repository such as `multilib-testing` will be resolved. This smart interface obsoletes all the `commitpkg` symlinks (e.g. `extrapkg`, `community-testingpkg`, etc.):

pkgctl release --staging libfoo pkgctl release --repo extra-testing newpkgthingie

By default the `pkgctl release` command will only commit, tag and upload the artifacts to the staging area on repos.archlinux.org. To update the binary package repository as the final step, either pass `--db-update` to the `release` command, or use the dedicated `pkgctl db` command:

pkgctl release --db-update

The `pkgctl db` command provides all required subcommands to interact with dbscripts such as move, remove and update. This obsoletes the requirement to setup local shell aliases or ssh directly to repos.archlinux.org to manage the repository sync database state:

pkgctl db update pkgctl db move extra-staging extra-testing libfoo libbar

## package build

The `pkgctl build` command will follow the same principles as `pkgctl release` by providing a smart interface to automatically detect which build target to use and will also provide `--testing` and `--staging` options to build against those special repositories. This will obsolete the need to directly call the currently used build scripts (e.g. `extra-x86_64-build`):

pkgctl build --testing --release --db-update

The build command will start as an incubating feature and may change in the future when we wire up a build service to the pkgctl interface. The build command will also receive more convenience options such as setting pkgver without the need to manually adjust the `PKGBUILD` with an editor.