Repository standards

All Garuda Linux code lives in the garuda-linux GitLab group. This page explains where a new repository belongs, which files it needs and how its commits, releases and packages work.

Where a repository belongs

Subgroup	What goes there	Example
applications/	Garuda applications	applications/toolbox
themes-and-settings/settings/	Settings packages for editions and desktops	themes-and-settings/settings/garuda-dr460nized
tools/	Build and CI tooling	tools/iso-profiles, tools/gitlab-ci-commons
Group root	Projects that span the whole distribution	pkgbuilds, garuda-nix

Repositories that are no longer used move to the archive repository, for example old PKGBUILDs and settings packages.

Adding a repository

1. Create the project in the right subgroup and pick a license. Every repository has a LICENSE file.

2. Add a README.md with what the project does, how to report issues and how to contribute. Packaging issues go to the PKGBUILDs repository, issues with the code or settings go to the repository itself.

3. Add a .gitlab-ci.yml that includes the shared templates from gitlab-ci-commons. At least the commitizen check belongs in every repository:

   .gitlab-ci.yml

   stages: [auto, test]
   
   include:
     - "https://gitlab.com/garuda-linux/tools/gitlab-ci-commons/-/raw/main/templates/commitizen.gitlab-ci.yml"

4. Add the files from the table below that apply to the project.

5. If the project becomes a package, add its PKGBUILD to the PKGBUILDs repository. See Packages.

Standard files

File	When	What it does
LICENSE	Always	The license of the project
README.md	Always	Description, issues and how to contribute
.gitlab-ci.yml	Always	Includes the shared CI templates
.gitlab/CODEOWNERS	Always	* @garuda-linux, so the team reviews merge requests and Renovate assigns its reviewers
.cz.yaml	Repositories with releases	Commitizen settings, for example tag_format: $version for tags without a v
flake.nix	Repositories with a dev shell	Dev shell and checks. The pre-commit hooks come from git-hooks.nix with commitizen and treefmt
renovate.json	Repositories with dependencies	Renovate updates, with lock file maintenance and Nix support
transifex.yml	Translated projects	Tells the Transifex GitLab integration which files to translate
.editorconfig	Optional	Shared editor settings
_typos.toml	Repositories that run typos	Words the spell check accepts

Commit messages

Every commit uses a conventional commit message with the Angular types. The changelogs and releases are generated from these messages, and the commitizen CI job rejects other messages.

Typical messages look like this:

fix: xyz not working
feat: add new waybar icon
style(garuda-fish-config): improve spacing

A scope in brackets is only needed in the PKGBUILDs repository, where it names the package the commit belongs to.

• Keep the message short, about 50 characters.
• Write it in the imperative: “If applied, this commit will …”
• Write for the changelog. Types such as build and chore stay out of it.
• Use one commit per feature. Squash related commits.

Commitizen writes a fitting message with cz commit. It is in the Nix dev shell of repositories that have one, or install it with pip install --user -U commitizen.

Shared CI templates

The templates live in gitlab-ci-commons. Include the ones a project needs.

Template	What it does
commitizen.gitlab-ci.yml	Checks that the commit title is a conventional commit message
flake-check.gitlab-ci.yml	Runs nix flake check. Set ALL_SYSTEMS: "false" to check only the runner’s system
pre-commit-nix.gitlab-ci.yml	Runs the pre-commit hooks of the flake dev shell on all files
tag-to-release.gitlab-ci.yml	Creates a GitLab release for every tag, with the changelog that commitizen writes for it
transifex-automerge.gitlab-ci.yml	Merges the translations_* branches that Transifex pushes into the default branch
qtlinguist-update.gitlab-ci.yml	Updates the Qt Linguist translation sources of Qt applications on the default branch

Packages

All PKGBUILDs are in the PKGBUILDs repository, never in the source repository. Each package has its own folder with the PKGBUILD and a .CI/config file that tells the pipeline how to build and update it.

There are two kinds of packages:

Kind	Where the sources are	How to release
Small packages, such as text files	In the package folder of the PKGBUILDs repository	Bump pkgver and push. The pipeline deploys every package whose folder changed
Packages built from their own repository	In the project’s own repository	Push a new tag to the project, without a v in front. The scheduled pipeline of the PKGBUILDs repository updates the PKGBUILD and deploys it

When a release also needs packaging changes, change the PKGBUILD in the PKGBUILDs repository and raise pkgrel only. The build status of every package of the garuda repository is visible in the PKGBUILDs pipelines.

Notifications

GitLab posts commits, merge requests, comments and failed pipelines to the Garuda development updates channel on Telegram.