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, though it might take a while. (We're busy!)

Remember, it takes effort to create a package. 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 name is not taken by other packages in Fedora repositories.
Review our packaging policies.
Review our custom SRPM macros

Preparation

Install Andaman (opens in a new tab) on your system and its mock configs
- sudo dnf install anda terra-mock-configs via Terra
- anda is also available via rust crates.io
Use rust2rpm for Rust packages
Use pyp2rpm for Python packages
Use go2rpm for Go packages
else, find the source of the packages you are adding, preferably a URL to a .tar.gz archive
- multiple archives are ok
- non .tar.gz archives are also ok, but might require additional build dependencies
- we also prefer archives from git repositories

Writing sources

Fork/clone the Terra sources repo (opens in a new tab)
Create a folder named after the package name.
- e.g. you are creating a font package lovelyfonttype. Create anda/fonts/lovelyfonttype
- A Pantheon DE package goes into anda/desktops/elementary/.
Inside the folder, create anda.hcl and <packagename>.spec
- note: font packages in Fedora repos should end with -fonts, i.e. the folder name is lovelyfonttype but your 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.

Editing the Spec file

TIP: Check out other spec files for other 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:       deps here
# We *highly* encourage you to add yourself as the packager here:
Packager:       Your Name <[email protected]>
 
%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
/usr/bin/pkgname-binary
/path/to/more/files/*/package
 
%changelog
* Wed Jan 11 2006 your-username-here <[email protected]>
- Description on what you've done

Add Source0 or Source1 or more. These preambles should link to a compressed file (preferably tar) 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, 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 dnf builddep path/to/pkgname.spec!

You don't need to create pkg. It's not supposed to exist
Modify the architecture to match your machine
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 will be inside anda-build/

Done?

Git commit and push; remember you must sign your commits!
Create a pull request that merges to the main branch

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"
    ...
  }
}

SRPM Macros

We provide SPRM macros to ease packaging and better integrate into our workflow. Please use these macros over their counterparts when possible.

These are provided in the anda-srpm-macros package, if you use them, make sure to add anda-srpm-macros as a BuildRequires in the spec file.

Macro	Function
`%cargo_prep_online`	Enables internet access for `cargo`. Replaces `%cargo_prep` and should be used in `%prep`
`%cargo_license_online`	Replaces `%cargo_license` in `%build`
`%cargo_license_summary_online`	Replaces `%cargo_license_summary` in `%build`

Automatic Updates FAQ