Policies and Guidelines

This document outlines all policies and guidelines specific to Terra and its subrepos.

Packagers and maintainers MUST follow the policies and guidelines 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 Extra" instead via the extra = 1 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 version 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.

Tags

First of all, the term "tag" is used to refer to different versions of the same software, as in their release schedule/model. For example, the zed package has 3 tags: stable, preview and nightly. (Some packages use tip instead of nightly.) Tags may be named after git branches from upstream.

Having a different tag of the same software warrants a separate package, i.e., they MUST have separate spec files with separate Name:s. The tag SHOULD be specified in Name: using the format %{rawname}.%{tag} e.g. ghostty.tip, zed.preview, and kf6-kio.switcheroo.

Packages without any tags specified in Name: MUST be regarded as stable.

For UX reasons, some packages MAY consider specifying Provides: %{rawname}-%{tag}.

Versioning

Packages SHOULD follow one of the version formats below:

## (a)
Version:  %{latest_stable_version}
## (b)
Version:  %{latest_stable_version}^%{commit_date}git.%{shortcommit}
## (c)
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 one of (b) and (c) is used, you MUST also include labels { nightly = 1 } in anda.hcl unless there is no update.rhai, as these 2 formats rely on the assumption that there is 1 %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.

(c) SHOULD be preferred over (b) if possible, since having a %unreleased_version can indicate to users breaking changes/new features depending on the versioning system (usually SemVer).

If upstream does not provide a version, use (c) and treat %unreleased_version as 0.

Release Field

The Release: preamble MUST NOT contain information regarding upstream versioning, including but not limited to commit dates, commit SHAs, 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.

Development and Shared Libraries

Shared library packages SHOULD be suffixed with -libs. These packages SHOULD NOT contain anything except:

%_libdir/*.so.*
%doc …
%license …

Development library packages SHOULD be suffixed with -devel. These packages SHOULD NOT contain anything except:

%doc …
%license …
%_includedir/*
# ^ source files, depending on the language, could be in other locations
%_libdir/*.so
%_libdir/*.a
%_libdir/pkgconfig/%{name}.pc
# and other development files (.vapi, .typelib, .gir, …)

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.

Miscellaneous Packaging Guidelines

Packager Field

The package maintainer of a package SHOULD be added to the Packager: preamble as follows:

Packager: Raboneko <[email protected]>

Usages of the mold linker

We encourage the use of mold (opens in a new tab), which may speed up build times especially in large projects. You MAY enable it in C/++ projects by adding -fuse-ld=mold in CFLAGS/CXXFLAGS.

The %with_mold flag is enabled by default in anda-srpm-macros. mold is also preinstalled in the builders.

You can disable mold for Rust and Nim by using %bcond_with mold.

Interpreted Languages (Python, Ruby, etc.)

All packages using interpreted languages follow the traditional Fedora guidelines, with all dependencies must be packaged individually as they are considered runtime dependencies.

Dynamically compiled languages (C, C++, Vala)

Dependencies required for runtime MUST be packaged separately.

Statically compiled languages

As Terra does not strictly follow Fedora's reproducibility requirements, and we do not want large amounts of development libraries for them, packagers SHOULD vendor dependencies on build time.

Terra's mock sandbox has networking enabled, so builders can download the dependencies directly on build time.

Rust

• Generate the spec file using rust2rpm.
• You SHOULD NOT use the tradtional Fedora %cargo_prep macro. Use %cargo_prep_online from anda-srpm-macros instead, and you SHOULD remove the %generate_buildrequires macro, as it is useless.
• It is RECOMMENDED to use %cargo_license_online and %cargo_license_summary_online, although they are not a strict requirement.
• You SHOULD NOT use both %cargo_build and %cargo_install in the same spec file as cargo install might cause a rebuild due to a bug. You SHOULD only include either one of them. In most cases, you can just omit %cargo_build entirely and it will just build fine.

Example:

%prep
%autosetup -n %{crate}-%{version} -p1
%cargo_prep_online
 
%build
%{cargo_license_online} > LICENSE.dependencies
 
%install
%cargo_install

Go

You SHOULD NOT use the default naming (but you MAY Provides:) generated from go2rpm (except non-leaf packages), as an unnecessarily long package name with unnecessary information is bad for UX.

Use the go compiler directly instead of using Fedora's Go macros, as this will generate offline dependencies that we do not want to package. Alternatively, use the _online macro variants:

%prep
%goprep
%autopatch -p1
%go_prep_online
 
%build
%go_build_online %{goipath}
 
%install
%gopkginstall
install -m 0755 -vd                     %{buildroot}%{_bindir}
install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/

Nim

Use the %nim_prep and %nim_c src/pkgname macros.