Skip to content

feat: Update preparation section #54

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Owen-sz merged 6 commits into from
Jun 2, 2026
Merged

feat: Update preparation section #54

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a6de1f9
feat: update preparation section
Daeraxa May 29, 2026
b9bd0a7
restore aside fallback
Daeraxa May 29, 2026
6ecd48d
address feedback, add badge
Daeraxa May 30, 2026
a25379c
add steps component
Daeraxa May 30, 2026
ac4a674
line break under badge needs 2 brs
Daeraxa May 31, 2026
9541d34
wrap badge in div
Daeraxa Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 66 additions & 47 deletions src/content/docs/contributing/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
---
title: Contributing
description: "Get started contributing packages to Terra."
title: Getting Started
description: "Get started with contributing packages to Terra."
---

import { Aside } from "@astrojs/starlight/components";
import { Aside, Badge, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
import { Code } from "astro:components";
import RPMSpec from "@/components/spec.json";

# Overview

Thanks for contributing to Terra!
<div>
<Badge size="large" text="💙 Thanks for contributing to Terra!" />
</div>

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!
Expand All @@ -27,78 +27,97 @@ If you ever need help, hop into [our Discord server](https://fyralabs.com/discor
and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174).
</Aside>

# Creating a package
## Creating a package

## Before you begin...
### Before you begin...

- Make sure the package is not in the [Fedora repositories](https://packages.fedoraproject.org), and the package name is not taken.
- Review our [packaging policies](/contributing/policies).
- Review our [packaging guidelines](/contributing/guidelines).
- Review our custom [SRPM macros](/contributing/srpm), as these may be helpful to your package.

## Preparation
### Preparation

You'll need a few tools to get started, pick one of these sections, then continue to [Writing Sources](#writing-sources).

### Fedora/Ultramarine
<Tabs>
<TabItem label="Fedora/Ultramarine">
Make sure that you have Terra [installed](/usage/installing).

Install [Andaman](https://developer.fyralabs.com/andaman) and its Mock configs on your system:
If not, then add it with:

<Code code={`sudo dnf install terra-mock-configs`} lang="ansi" inline />
```sh
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release terra-gpg-keys
```

### Dev Container
Once enabled, install [Andaman](https://developer.fyralabs.com/andaman) and its [Mock](https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds) configs on your system:

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.
```sh
sudo dnf install anda terra-mock-configs
```

1. Install the Dev Containers extension in your IDE
- Zed comes with Dev Containers, see [this documentation](https://zed.dev/docs/dev-containers)
If preferred, Andaman can also be installed via [Cargo](https://crates.io/crates/anda)

- VSCode users need to install the Dev Containers extension
```sh
cargo install anda
```

2. Get the container runtime
- On Windows and Mac, install [Docker Desktop](https://docs.docker.com/desktop)
</TabItem>
<TabItem label="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.

- On Linux, install `podman-docker` from your package manager
<Steps>
1. Install a Dev Containers extension in your IDE:

3. Fork [terrapkg/packages](https://github.com/terrapkg/packages), and `git clone` your fork
4. Open the folder you cloned in your editor
5. It should prompt you to `reopen in Dev Container`, click this and wait for the Dev Container to open.
- Zed comes with Dev Containers, see [this documentation](https://zed.dev/docs/dev-containers)

<Aside type="tip">
If your editor doesn't prompt you, press `Ctrl` + `Shift` + `P`, and select
the "Reopen in Dev Container" (VSCode) or "Project: Open Remote" (Zed) option.
</Aside>
- VSCode users need to install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)

You are now in the Terra Dev Container, and have all the packages and
configuration necessary to start building packages!
1. Get the container runtime:

### Pet Container
- On Linux, install [podman-docker](https://podman.io/) from your package manager

If you're on atomic system, or otherwise prefer to work with containers, you can run the Terra build container as your development environment.
- On Windows and Mac, install [Docker Desktop](https://docs.docker.com/desktop)

Simply run:
1. Fork [terrapkg/packages](https://github.com/terrapkg/packages), and `git clone` your fork

```shell
podman run --rm --cap-add=SYS_ADMIN --privileged --volume ./:/anda --volume mock_cache:/var/cache/mock --workdir /anda ghcr.io/terrapkg/builder:frawhide anda
```
1. Open the folder you cloned in your editor

### Cargo
1. It should prompt you to `reopen in Dev Container`, click this and wait for the Dev Container to open.
</Steps>

Anda is also available via [Cargo](https://crates.io/crates/anda).
<Aside type="tip">
If your editor doesn't prompt you, press `Ctrl` + `Shift` + `P`, and select
the "Reopen in Dev Container" (VSCode) or "Project: Open Remote" (Zed) option.
</Aside>

### Language Support in Editors
You are now in the Terra Dev Container, and have all the packages and
configuration necessary to start building packages!
</TabItem>
<TabItem label="Pet Container">
If you're on atomic system, or otherwise prefer to work with containers, you can run the Terra build container as your development environment.

The most common languages you will see:
Simply run:

- 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
```sh
podman run --rm --cap-add=SYS_ADMIN --privileged --volume ./:/anda --volume mock_cache:/var/cache/mock --workdir /anda ghcr.io/terrapkg/builder:frawhide anda
```
</TabItem>
</Tabs>

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.
<Aside type="tip" title="Tip: Language Support in Editors">
The most common languages you will see:

- [RPMSPEC](https://rpm-software-management.github.io/rpm/manual/spec.html) (`.spec`), for the package build scripts
- [Rhai](https://rhai.rs/), for the auto-update scripts
- [HCL](https://github.com/hashicorp/hcl#readme), for informing `anda` of the package
- [XML](https://en.wikipedia.org/wiki/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 where possible.
</Aside>

### Writing sources

Expand Down
Loading