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 (opens in a new tab).
• 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

• After you've forked/cloned Terra (this repo), check for existing directories in anda/ for the corresponding category your package belongs to
  • If it doesn't belong to any, go to anda/
• 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.
• 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:        %autorelease
Summary:        A package example
URL:            https://example.com
Source0:        https://github.com/some/repo/archive/%{version}.tar.gz
License:        MIT
BuildRequires:  some dependencies >= 3.2.1 another-dep
Requires:       deps here
 
%description
This is a description of the package that literally does nothing.
 
%prep
%autosetup -n name-of-folder-after-source0-expansion
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-38-x86_64 anda/fonts/lovelyfonttype-fonts/pkg

• 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
• 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.

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.