Contributing

Thanks for contributing to Terra!

Terra is specifically designed to be as package-maintainer-friendly as possible — you don't need to know everything about the infrastructure to create a package for Terra! See the following guide for creating a new package yourself. Quick and easy.

It's also ok to suggest packages to include into Terra by raising a GitHub issue (opens in a new tab), though it might take a while. (We're busy!)

It takes effort to create a package, and as always, there is a learning curve. If you ever need help, hop into our Discord server (opens in a new tab) and we will try to help you.

Creating a package

Before you begin...

Make sure the package is not in the Fedora repositories (opens in a new tab), and the package name is not taken.
Review our packaging policies below.
Review our packaging guidelines.
Review our custom SRPM macros, as these may be helpful to your package.

Preparation

Fedora/Ultramarine

Install Andaman (opens in a new tab) and its mock configs on your system
- sudo dnf install terra-mock-configs via Terra
- anda is also available via rust crates.io
- If on an atomic system, this command works using podman: podman run --rm --cap-add=SYS_ADMIN --privileged --volume ./:/anda --volume mock_cache:/var/lib/mock --workdir /anda ghcr.io/terrapkg/builder:frawhide anda
Fork the Terra sources repo (opens in a new tab), and then git clone your fork.
You are now ready for the Writing Sources (opens in a new tab) section below.

Dev Container

You can create, build, and push a package all from within our Dev Container. This means you do NOT need to be running Fedora/Ultramarine to create a package. You can run this devcontainer from Linux, macOS, or Windows.

If you're Visual Studio Code, open it and navigate to the Extensions menu located at the bottom of the left sidebar.
Install Docker (opens in a new tab). If you're on Linux, you'll need to enable the service and reboot.
Fork the Terra sources repo (opens in a new tab), and git clone your fork.
Open this folder in Visual Studio Code (File -> Open Folder).
It should prompt you to reopen in Dev Container, click this and wait for the Dev Container to open. If it doesn't prompt you, press Ctrl + Shift + P, type Reopen in Container, and press Enter.
You are now in the Terra Dev Container, and have all the packages and configuration necessary to start building packages!

Language Support in Editors

The most common languages you will see:

RPMSPEC (.spec), for the package build scripts
rhai, for the auto-update scripts
hcl, for informing anda of the package
xml, for appstream metainfo on some packages

VSCode should prompt you to install these extensions, and Zed should auto-install them. If not/using a different IDE, we suggest installing language support for each of these.

Writing sources

Fork the Terra sources repo (opens in a new tab), and git clone your fork.
Create a folder named after the package name, for example:
- A font named lovelyfonttype would go in anda/fonts/lovelyfonttype.
- A Pantheon DE package would go in anda/desktops/elementary/.
Inside the folder, create anda.hcl and <packagename>.spec.
- Note that font packages in Fedora repos should end with -fonts, e.g. the folder name is lovelyfonttype but the spec file should be lovelyfonttype-fonts.spec.
- The name of the folder name actually is just for identifications for Terra package maintainers. What matters is that the spec file name must match with the package name defined in the spec file later. This is a Fedora mock limitation.
- For more information, check out our [packaging policies].

Edit anda.hcl, which tells Andaman (opens in a new tab) how to build the package:

project pkg {
    rpm {
        spec = "<packagename>.spec"
    }
}

Edit the spec file.
- It is a custom file format for RPM packages.
- This RPM Packaging Guide (opens in a new tab) might help newbies with no prior experiences with RPM specs.
- This Spec file format (opens in a new tab) docs goes into the details of the spec file format.
- You may use rust2rpm for Rust packages.
- You may use go2rpm for Go packages.
- Otherwise, find the source of the packages you are adding, preferably a URL to a .tar.gz archive
- Multiple archives are ok.
- Archives not in .tar.gz format are also okay, but might require extra work.
- Archives from git repositories are preferred.

Editing the Spec file

TIP: Check out other spec files of related packages for some examples ;)

A generic spec file looks like this:

Name:           pkgname
Version:        1.2.3
Release:        1%?dist
Summary:        A package example
URL:            https://example.com
Source0:        https://github.com/some/repo/archive/%{version}.tar.gz
# You should change the above link to the source tarball you got from the preparation section
License:        MIT
BuildRequires:  some dependencies >= 3.2.1 another-dep
Requires:       runtime deps here
# We require you to add yourself as the packager here (if this is an issue for you, let us know):
Packager:       Your Name <meowy@example.com>
 
%description
This is a description of the package that literally does nothing.
 
%prep
%autosetup -n name-of-folder-after-source0-expansion
# if you are not using a tarball, simply use normal shell commands to extract the sources
echo "hai"
 
%build
echo "this will run when building pkg"
 
%install
echo "this will also run when building pkg but for installing it into %{buildroot} so that anda (mock) can package it"
 
%files
# This macro expands to `/usr/bin`. To see what macros expand to, you can run `rpm --eval %{MACRO}`
%{_bindir}/pkgname-binary
/path/to/more/files/*/package
 
%changelog
* Wed Jan 11 2006 your-username-here <your_email@idk.xyz>
- Description on what you've done

Add Source0 or Source1 or more. These preambles should link to a compressed file (preferably a tarball) and will be extracted during %prep. You should've had the link prepared during #Preparation :3
Add a new line %prep
- The source file will be automatically downloaded and extracted with %autosetup -n <root dir name in tar file> inside %prep. Check out blackbox-terminal.spec as an example
- If it is not a tar archive, extract the file manually with a command. See authy.spec as an example (unsquashfs)
Inside %build, you might need to build the package. Macros like %meson and %cmake are supported. Check out blackbox-terminal or prismlauncher
- if not, manually state the command
List out all the files to be included inside %files
- Use %doc to state the README file (if it exists)
- Use %license to state the COPYING or LICENSE file (if it exists)
- TIP: If you are unsure about the files to install, run the build first. mock will show you the files not packaged but installed via an error
Add %changelog (message preferably "Initial Package")

Building

Having anda installed (or in the Dev Container) run the following command:

anda build -c terra-rawhide-x86_64 anda/fonts/lovelyfonttype-fonts/pkg

If you would like to use the rpmbuild mode instead (which will instead not set up a container), add --rpm-builder=rpmbuild. Remember to install the build dependencies using sudo dnf builddep path/to/pkgname.spec!

You don't need to create pkg. It's not supposed to exist, just needs to be at the end of the build command
Modify the architecture to match your machine (x86_64, i386, aarch64)
If needed (404 errors when building off rawhide, you can also modify the version it builds on (43, 42, el10, etc.)
If the package fails to build, fix your spec file accordingly
- Usually the actual useful error message can be found before the Python traceback (from mock).
The built RPM(s) will be inside anda-build/

Done?

Git commit and push; remember you must sign your commits!
Create a pull request that merges to the frawhide branch, this is equivalent to main or master

Automatic updates

The system regarding automatic updates are described here. Here is an overview:

Andaman (opens in a new tab) supports updating via .rhai packages. See the "book" (more like guide) for Rhai (opens in a new tab).

Create update.rhai inside the package folder.
See references from other packages.
You also need to add labels { nightly = "1" } in anda.hcl for nightly packages.

Remember to add semicolons in Rhai scripts! (;)

Anda defaults the filename to update.rhai. If it's not update.rhai, add a new entry inside anda.hcl:

project pkg {
  rpm {
    update = "path/to/update.rhai"
    ...
  }
}

Policies

Packagers and maintainers MUST follow the policies listed in this document.

Submission Policy

Use common sense.

When it comes to submissions, anything is fair game, assuming that our policies are followed. However, there is a mild exception for GUI applications.

Please refrain from submitting applications that work perfectly fine as a Flatpak, unless there is a technical or UX justification for it. Examples of these exceptions are:

Application Type	Justification
Terminal Emulators	These often only work properly when run directly on the host system.
CLI/TUI applications	The UX of Flatpak isn't optimized for these types of applications. (ex. requiring the user to call Flatpak, and then the RDNN of the app)
Modded/Multi-instance game launchers (i.e Minecraft launchers)	May require access to system libraries, and can be better managed by the user when not sandboxed. For example Minecraft launchers can easily access multiple JRE installations when not sandboxed.
Other appliactions that require manual modification of data files	Requires user to modify its data files regularly, applies in the same above case.
Applications that suffer major performance or technical issues due to sandboxing (IDEs, text editors, file managers, DAWs and other applications that rely on native plugin support like VSTs or LV2, etc.)	These applications usually require systems libraries to be present to work properly.
System components	These packages simply cannot be sandboxed, as they are part of the operating system itself.
Libraries required to build or use the aforementioned packages	These libraries are required to build or use the aforementioned packages, and are usually not sandboxed.

Other applications that are not specified here may be allowed on a case-by-case basis.

You MUST have the rights or permission to redistribute the packaged software. Besides that, there is no prohibition on proprietary licenses.
Submissions must be maintained. We will reject submissions of unmaintained software.
Submissions MUST NOT be malicious.
Submissions that may introduce breaking changes must be included in "Terra Extras" instead via the subrepo = "extras" label in anda.hcl.
- Example: terra-mesa should be in extra as the dependency solver will resolve this package for matching "provides" (such as mesa-libEGL(x86-64)).
- Example: libadwaita-nightly should be in extra since it provides pkgconfig(libadwaita-1), which is required by existing packages as a build dependency.
- Example: yt-dlp-nightly can be included normally because it has no common provides with Fedora's yt-dlp.
- If you are in doubt whether your submission should be in extra instead, ask and we will decide.
Submissions SHOULD include an auto-update script (update.rhai).
Submissions SHOULD be placed in the corresponding directory in anda/.
- Each folder MUST either contain folders and no source files (other files are exempted), or contain multiple files and no folders.
- The following directories have a higher priority. Categorize your new package in the following order:
  1. fonts/
  2. system/ (bootloaders, kernels, drivers, ...)
  3. tools/buildsys/ (software used to build other software)
  4. devs/ (tools for software development)
  5. games/
  6. themes/
  7. docker/ (software related to containers)
  8. desktops/ (applications specific to a Desktop Environment)
  9. apps/ (GUI applications)
  10. langs/ (software written in/for a specific programming language)
When there are ambiguous or unspecified parts in our policies/guidelines, you SHOULD refer to Fedora's packaging guidelines (opens in a new tab).
Low-quality contributions will be declined at the team's discretion.
Do not include work-in-progress code or untested patches. See https://dont-ship.it/ (opens in a new tab).

Maintenance Policy

Anyone MAY make a PR (pull request) to an already existing package.
Unmaintained packages may be removed at any time. Before doing so, we will create a GitHub issue to gauge community interest.
Terra will only support the latest versions of Fedora, if a package doesn't build on the next version of Fedora, we might hold it back.

Naming and Versioning Scheme

This section describes the guidelines for naming and versioning packages correctly in both Terra and Terra Extras.

Versioning

VCS	ID
Git	`git`
SVN	`svn`
CVS	`cvs`
Bazaar	`bzr`
Mercurial	`hg`
Perforce (Helix)	`p4`
Pijul	`pjl`
Azure DevOps	`tfs`
darcs	`drc`
Fossil	`fsl`

Packages SHOULD follow one of the version formats below:

## (Release tag tracking (stable))
Version:  %{latest_stable_version}
## (Commit tacking (nightly off version tag))
Version:  %{latest_stable_version}^%{commit_date}git.%{shortcommit}
## (Commit tacking (no stable version tag))
Version:  %{unreleased_version}~%{commit_date}git.%{shortcommit}

git SHOULD be replaced with the correct VCS identifier for (b) and (c) as listed on the right.

If either commit tracking option is used, you MUST also include labels { nightly = 1 } in anda.hcl unless there is no update.rhai, as these two formats rely on the assumption that there is one %shortcommit for each %commit_date (and vice versa).

%unreleased_version refers to the expected version number for the next stable (or a more stable tag than nightly) release, while %latest_stable_version refers to the current latest released version number, preferably stable.

Commit tacking (nightly off version tag) SHOULD be used when there is a stable and nightly version of a package.

If upstream does not provide a version, use Commit tacking (no stable version tag) and replace %unreleased_version as 0.

Release Field

The Release: preamble MUST NOT contain information regarding upstream versioning, including but not limited to commit dates, commit hashes, software versions, tags, etc. Without approval from the team, packages MUST use the format Release: 1%?dist (or 1%{?dist}).

The release number SHOULD be incremented if changes are made to the package, unless the Version: changes.

Naming

Prefix/Suffix the packages in the following order (that means nightly fonts should end with -fonts.nightly)

Fonts MUST be suffixed with -fonts.
Shared libraries SHOULD be either suffixed with -libs.
- Alternatively, the lib prefix is also allowed, but they SHOULD still provide -libs.
Development libraries SHOULD be suffixed with -devel.
If necessary, suffix -bash-completion (or other shells) and -doc.
Postfix a tag if necessary (e.g. .nightly).

Miscellaneous Terra Policies

Security Policy

Our security policy is documented in the SECURITY.md file (opens in a new tab).

Code of Conduct

Our code of conduct is documented in the CODE_OF_CONDUCT.md file (opens in a new tab).

Lifecycle Policy

Our support lifecycle is documented in the lifecycle page.

Automatic Updates FAQ