You've been running Debian for a while and you're comfortable administering it. This is where you stop being just a user of Debian and make your first real contribution back to it.
Part of the awesome-debian factory line.
Input: someone comfortable administering their own Debian system (the output of Station 3, debian-power-user). Station 4 — debos-build-action, debos-custom-os, live-build-iso-action — is a parallel branch of the pipeline (building your own images), not a strict prerequisite for this station.
Output: your first real upstream interaction with Debian — a filed bug that gets triaged, or a first tiny package built and sanity-checked. Ready for Station 6 — debian-specialize.
Honest framing up front: this station gets you to your first contribution, not to Debian Developer status. Becoming a Debian Maintainer or Developer is a months-long process involving sponsorship and community trust — this guide is the on-ramp, not the whole road.
- Filing a Good Bug Report
- Finding a Good First Bug
- Salsa: Debian's GitLab
- mentors.debian.net and the New Maintainer Process
- Building Your First Tiny Package
- Using the Lintian-Check Workflow Template
- Further Reading
The standard way to file a bug against a Debian package is reportbug (install it with apt install reportbug), not a plain email or a random web form. Run it against the package you're reporting on — reportbug <package-name> — and it automatically attaches the package version, your architecture, and other metadata that Debian's Bug Tracking System (BTS) needs to triage the report properly. Skipping reportbug and filing free-form is the single most common reason a first-time bug report gets stuck asking for basic info instead of getting looked at.
A report that actually gets acted on has:
- Exact steps to reproduce — commands run, in order.
- Expected behavior vs. actual behavior — stated separately, not implied.
- The package version (
reportbugattaches this automatically; if you're not using it, get it withdpkg -l <package>).
Debian's Bug Tracking System (bugs.debian.org) supports tags and usertags, and newcomer-friendly bugs are sometimes tagged in ways that make them easier to search for. If you're not sure where to start, it's completely normal to ask on Debian's IRC/Matrix channels or mailing lists for a pointer to an approachable open bug in an area you're interested in, rather than trying to search blind.
Most Debian packages are maintained in git repositories hosted on Salsa (salsa.debian.org), Debian's own self-hosted GitLab instance. To contribute a fix:
- Create a Salsa account.
- Find the package's repo (usually under a team namespace or the maintainer's personal namespace).
- Fork it, clone your fork, make your change on a branch.
- Open a merge request against the original repo, same as you would on GitHub or any other GitLab instance.
The workflow itself is standard Git/GitLab — the Debian-specific part is understanding the packaging conventions inside the repo (see "Building Your First Tiny Package" below), not the git mechanics.
If you want to get a new package into Debian (rather than fixing an existing one), the on-ramp is mentors.debian.net: you upload your package there, and an existing Debian Developer acts as your sponsor, reviewing and eventually uploading it on your behalf until you've built enough of a track record to apply for upload rights yourself via Debian's New Member process.
Be realistic about the timeline: sponsorship and review cycles are measured in weeks to months, not days, and that's by design — it's how Debian keeps its quality bar. Don't let that discourage you from starting; just don't expect a same-week merge.
The general shape of packaging something for Debian:
- Scaffold it.
dh_make(from thedh-makepackage) generates a startingdebian/directory for a source tree you're packaging. - The key files it creates:
debian/control— package metadata: name, dependencies, description.debian/rules— the build recipe (almost always just a thindh $@wrapper via debhelper today).debian/changelog— every change to the packaging, in a specific formatdch(also fromdevscripts) helps you maintain correctly.
- Build it. Either
dpkg-buildpackagedirectly, orgbp buildpackageif you're usinggit-buildpackage's conventions (adebian/branch structure that plays well with Salsa). - Check it before showing anyone. Run
lintianagainst the resulting.deb/.changes— it's Debian's static analyzer for packaging mistakes, and a cleanlintianrun is the baseline expectation before you ask anyone to review your work, not an optional nice-to-have.
This is exactly what the workflow template below automates.
templates/lintian-check.yml is a copy-paste template, not this repo's own CI (this repo has no Debian package in it, so the workflow would have nothing to build here — copy it into your own first-package repo).
What it does: on every push, it spins up a debian:trixie container, installs build-essential, devscripts, dpkg-dev, and lintian, builds your package's source with dpkg-buildpackage -us -uc -S (source-only, no signing needed in CI), then runs lintian against the result and fails the job on any lintian error. This mirrors what Debian's own real infrastructure does for every package on Salsa via the Salsa CI pipeline — the official reusable CI used across salsa.debian.org, covering lintian, piuparts, autopkgtest, and reprotest. This template is a lightweight GitHub Actions equivalent of the lintian stage specifically — a genuine upstream Debian package should eventually be checked with the real Salsa CI pipeline once it's on Salsa, not just this template.
To use it: copy templates/lintian-check.yml into your own package repo's .github/workflows/, adjust the working directory if your debian/ folder isn't at the repo root, and push.
- reportbug — Debian Wiki
- Debian Bug Tracking System
- Salsa (salsa.debian.org)
- mentors.debian.net
- Debian New Member process
- dh_make / dh-make — Debian Wiki
- Salsa CI pipeline
- Lintian
See CONTRIBUTING.md. This station holds itself to the same "sourced, not guessed" bar as debian-hardware-and-gaming.
CC0 1.0 Universal — public domain dedication.