Contributors Guide
We are looking to collaborate with the community to help make stillOS even better. With that, we are trying to make it very easy to contribute. This document goes over different core components of stillOS and what they do. If you are interested in contributing, please join the stillHQ Community Discord Server where we build in public. In the Discord our contributors will be happy to help you get started contributing.
stillOS is split across focused projects in the stillHQ GitLab group. Start in the repository that owns the behavior you want to change.
Find the right project
| Purpose | Project | Languages | License | What it does |
|---|---|---|---|---|
| Software Management | stillCenter | Python, Shell, CSS | GPL-3.0-or-later | GTK Curated Software Center |
| Software Management | SAM | Python, Shell | GPL-3.0-or-later | Performs privileged package operations, alternative to PackageKit built for the ground up to handle multiple package management systems on stillOS |
| Software Management | SaDB | Python, Shell | GPL-3.0-or-later | Supplies package metadata |
| Software Management | SaDB Repo | Python, Shell | MIT | Contains application catalog entries |
| Desktop Experience | stillControl | Python, Shell | MIT | Manages desktop customization |
| Desktop Experience | Quick Setup | Vala, Python, Shell | GPL-3.0-or-later | Handles onboarding |
| Desktop Experience | stillExplore | Vala, Shell | MIT | Welcome and resources app |
| Desktop Experience | SAM GNOME extension | JavaScript, CSS, Shell | GPL-3.0-or-later | Integrates SAM with GNOME |
| Terminal Experience | stillTerminal | Vala, Python, Shell, CSS | GPL-3.0-or-later | Terminal |
| Terminal Experience | still-zsh | Shell, Python | GPL-3.0-or-later | Configures the stillOS ZSH experience |
| Web Apps | SWAI | JavaScript, CSS, Shell, HTML | GPL-3.0-or-later | Runs web apps from .swai manifests |
| Web Apps | swai_inst | Python, Shell | GPL-3.0-or-later | Installs and updates SWAI bundles |
| Identity and Packages | stillOS packages | RPM spec files, Shell | Varies by package | Builds packages for our COPR repository |
| Documentation | stillhq-docs | Markdown, HTML, CSS | CC BY 4.0 | Contains this documentation site |
When contributing documentation, tutorials should state their stillOS version, prerequisites, exact commands, expected result, and recovery steps.
Submit a change
- Read the target project's README and contribution files. Open an issue before broad architectural work.
- Fork the project and branch from its current default branch. Branch names
vary across stillHQ, so do not assume it is
main(sometimes it ismaster). - Use the project's own toolchain: commonly Meson for Vala apps, Python and RPM tooling for GTK apps and services, npm for SWAI, Go and Make for the image builder, or YAML with CI validation for the application catalog.
- Keep the merge request focused. Add tests where the project has them and update translations, assets, and user documentation when behavior changes.
- Run the available checks locally, then confirm that the GitLab pipeline passes. Explain what changed, how you tested it, and any known limitations.