Contributing
UFLinux is a small project with a narrow testing surface, so the most useful contributions are the narrow ones.
Where to file things
Section titled “Where to file things”| Problem | Where |
|---|---|
| Something wrong or missing on these pages | UFlinux-project/docs |
| Distribution, packages, images, installer | UFlinux-project/uflinux3 |
When reporting a hardware problem, say which architecture and firmware mode you used, and whether you were on an ISO or a device image. “Does not boot” on riscv64 is expected and not the same as “does not boot” on x86_64 — see Architectures and boot.
Before you change the distribution
Section titled “Before you change the distribution”Run the repository checks first:
python3 scripts/check.pyshellcheck -S warning scripts/*.sh profiles/*.sh tests/*.shactionlint -config-file .github/actionlint.yaml .github/workflows/build.ymlThe actionlint config recognises the documented Ubuntu runner labels because its built-in runner list can lag GitHub’s releases. It does not provision self-hosted runners; the workflow continues to request GitHub-hosted runners.
Then read Building for the stages and work-directory rules, and Maintenance for what a change to a pinned input implies. A change to ConnMan, the desktop shell, runner images, QEMU, firmware or Alpine’s kernel means the relevant tests have to pass again — failed targets are not marked optional to make a release happen.
Documentation contributions
Section titled “Documentation contributions”These pages are a reader-facing rewrite of the developer notes in uflinux3, so a good docs
contribution usually takes one of these forms:
- a missing step or wrong flag in a procedure;
- a claim that overstates what upstream actually claims — the project is careful about hedging, and a page that says “supported” where upstream says “built but never booted” is a bug;
- a Czech translation improvement.
Pages derived from upstream carry a source: frontmatter field and a link to the exact upstream
file at the bottom. If you change one, keep both in place.
Editing this site
Section titled “Editing this site”The site is Astro Starlight. English pages live directly in
src/content/docs/, Czech translations in src/content/docs/cs/ with mirrored slugs, so an
untranslated page falls back to English rather than 404ing.
npm installnpm run dev # local previewnpm run check # type and content checknpm run build # production build into dist/The sidebar is defined explicitly in sidebar.mjs rather than autogenerated, so a new page also
needs an entry there — with its Czech label in translations — or it will not appear in the
navigation.
Deployment is Cloudflare Pages connected to the repository; see the repository README for the build settings.
Licensing your contribution
Section titled “Licensing your contribution”UFLinux scripts, Settings and configuration are GPL-3.0-only, matching the repository licence.
Anything you contribute to the distribution falls under that. Documentation in this repository is
under the same licence.