Contributing to InterGenOS

InterGenOS is a Linux distribution built entirely from source, currently at version 1.0-dev (build id v1.0-dev1). It ships a custom package manager (pkm), the Forge installer, a signed boot chain with dm-verity sealing the live image and UKI signing (Secure Boot enforcement optional, off by default on the current fleet), and a tiered, offline-first local AI assistant (InterGen). Today the desktop is GNOME 49 on Wayland. Contributions of all kinds are welcome.

The guiding principle

Every contribution must serve the project’s core purpose:

InterGenOS exists to put the user in control of their own machine. Every design decision, every default, every included component must serve this purpose: giving people a system they understand, can modify, and can trust.

If a change adds complexity that does not serve the user, it is not welcome, regardless of how conventional it may be. The result we are after is a machine you understand, can modify, and can trust.

The three lenses

Before any development decision is made — a recipe edit, a fix, a build flag, a package choice, a process step — it is run through three lenses, in order. They are the working filter for every choice. An option that fails any one of them is wrong, no matter how convenient, conventional, fast, or precedented it is.

1. Security is not first. It is only. We build assuming adversaries have superhuman vulnerability-discovery capability. The question is always whether a change eliminates silent failure and turns an unverified assumption into a checked gate. A masked error, a blanket “ignore failures,” an unverified “known-good” claim, or a degraded-but-shipped feature is exactly what such an adversary exploits. If an option masks rather than verifies, it is wrong.
2. The user controls a machine they understand, can modify, and can trust. We reject bespoke complexity that hides how the system works, and prefer the standard, transparent, built-from-source path even when a shortcut would be more convenient. A machine the user cannot trust is a machine they do not control.
3. Logic and project intent. Does the choice satisfy everything it is evaluated against — secure, from-source, reproducible — and the actual goal behind the work? A locally clever answer that defeats the project’s stated intent is wrong.

These lenses usually converge on a single answer. When they do, that is the answer.

How to contribute

Reporting issues

• Use GitHub Issues for bug reports and feature requests.
• For build failures, include the package name, version, and build log output.
• Check existing issues before opening a new one.
• For security vulnerabilities, follow the project’s SECURITY.md policy rather than filing a public issue.

Code contributions

InterGenOS is currently maintained by a single developer. To contribute code:

1. Open an issue first to discuss the change.
2. Fork the repository and create a branch.
3. Follow the existing code style — no surprises.
4. Test your changes; the build must remain reproducible.
5. Submit a pull request with a clear description.

Package templates

The most impactful contributions are package templates. Each package lives under packages/<tier>/<name>/ and needs two files:

• package.yml — metadata: source URL, SHA256, dependencies, and build style.
• build.sh — bash functions configure(), build(), check(), and do_install().

Follow the BLFS 13.0 book for build instructions, and use DESTDIR="" for all installs.

Packages are organized into six tiers — toolchain, core, base, desktop, ai, and extra. As of June 2026 the tree carries roughly 857 packages across those tiers (about 28 toolchain, 272 core, 23 base, 420 desktop, 2 ai, and 112 extra). These counts drift as the tree evolves, so derive the live numbers from the source tree rather than treating any figure as fixed.

What we value

• Research before implementing. Check the LFS/BLFS book and study how other distributions handle it. A short investigation beats hours of trial and error.
• Simplicity over cleverness. If there is a simpler way, use it.
• Transparency. No hidden behavior, no magic.
• Tested changes. If you cannot verify it works, do not submit it.

Security standards

InterGenOS is built for hostile-network resilience. The project assumes adversaries have superhuman vulnerability-discovery capability and treats every package, configuration, and code change as potentially within their reach. All contributions are reviewed against current best-practice vulnerability-discovery tooling before merging.

Contributions that introduce any of the following will not be accepted:

• Known vulnerabilities — code patterns flagged by static analysis, dependency chains with published CVEs, or configurations that weaken the system’s security posture.
• Supply chain risks — unverified source tarballs, missing or incorrect SHA256 checksums, dependencies fetched from untrusted origins.
• Privilege escalation vectors — improper setuid usage, world-writable files in privileged paths, or unsafe default permissions.
• Feature regressions disguised as fixes — disabling functionality or removing dependencies to work around build failures rather than resolving the root cause.

If review surfaces an issue in your contribution, the maintainer will work with you to resolve it before merging. Security is not negotiable.

Public content audit

All pull requests to master are scanned by an automated public-content audit (.github/workflows/public-content-audit.yml). This check ensures that internal development artifacts — host-specific paths, internal file references, and credential-like strings — do not enter the public repository. If the audit fails on your PR, amend the flagged files and push again. Legitimate public content that happens to match a flagged pattern can be added to scripts/check-public-content.allowlist.

The doctrine: only a clean build counts

A build whose packages all compiled is not a build that is known-good. The expensive failures of a from-source distribution are not compile errors. They are the class of defect that compiles fine, packages fine, and only manifests when the artifact is installed and booted on real hardware: a service unit locked down with no writable path, a directory omitted from a package’s file list, a hardware-detection heuristic wrong for an integrated GPU, a first-boot race. None of these is caught by “all packages built, 0 failures.” Every one is caught by installing the artifact and booting it on real hardware.

Two laws follow:

1. Validate on a clean build and install, on hardware that reproduces the bug — never on a hand-patched development box. Nothing is done until the fix lives in the source tree and a clean build reproduces the corrected behavior with zero manual intervention (the signing step is the one sanctioned human action). A fix that only works because of a manual edit on the running target is a note about a fix, not a fix.
2. Fixing now is the default for trust-bearing, build-orchestration, and small gaps. An unfixed gap compounds. When immediate repair is genuinely not the right call, that exception is recorded with an explicit expiry condition and a way to measure it, never as a bare line on a list.

Race-class fixes carry two extra requirements: validate on the hardware that actually reproduces the race (the slower, lower-end tier is the honest test), and require several consecutive clean cold boots. A single clean boot does not clear a race, and a warm reboot is not a substitute for a cold power-cycle.

The build lifecycle

InterGenOS is produced as an ordered, reproducible lifecycle. A full from-scratch build runs 20 phases in a fixed order inside an isolated, reproducible build environment:

validate → verify-sources → setup → toolchain → chroot-prep → chroot-tools → core → config → core-extra → base → kernel → desktop → ai → extra → bootloader → image → manifest → squashfs → ukis-verity → iso

An optional publish step pushes the result to the signed package mirror. The stages group into these decision gates:

1. Build from source — the proving ground. Every source is pinned and checksum-verified before use; the build is deterministic by construction (full byte-identical reproducibility across independent builders is a 1.x goal). Minting a candidate is deliberately expensive so that what comes out of it has earned trust.
2. Handle build issues without cheating. A failure is fixed in the source tree, never worked around. No moving a package to a different tier to dodge a wiring problem, no disabling a feature to bypass a missing dependency, no silently skipping a failed step, no stub functions (“a stub is a lie”). Disabling a package’s test suite is a last resort, not a first response. After a few failed tactical attempts on one problem, the process stops and switches to research-first investigation rather than thrashing.
3. Sign the boot chain. The build halts for a hardware-token signing step. One signing covers the bootloader and all of the unified kernel images. Each kernel image’s command line carries the verified-integrity root hash of the read-only system image, so a tampered system image cannot boot under a validly signed kernel. Signing only appends a signature; it never alters the payload.
4. Assemble the ISO. The read-only system image is compressed, a dm-verity hash tree is generated over it, and the bootable ISO stages the signed bootloader and kernel images alongside it. Integrity verification (root hash sealed in the signed kernel command line) is the primary path, with a whole-file checksum fallback; both are asserted non-empty at build time and verified again at boot.
5. Pre-install evaluation. The ISO is booted on real hardware (or a Secure-Boot-capable test VM) and the live environment is examined before any install: the Secure-Boot and integrity chain, the system and user logs, failed units, and the shipped security posture (the system ships locked — no remote access enabled, default-deny firewall). A clean smoke pass does not by itself guarantee a clean install.
6. Install and post-install evaluation. The installer writes the system to disk, then the result is examined exhaustively, not as a spot-check. The full installer trace is read end to end, the install-run journals are read, the system is rebooted into the installed target, and the installed logs are read for every boot — confirming zero failed units and a clean boot-chain trust record. Every operator observation and every log anomaly becomes a tracked issue.
7. Track issues, then iterate. Findings are grouped into layers applied and validated together, so a regression localizes to its layer. For day-to-day iteration, a single rebuilt package can be slipstreamed into the install set without rebuilding the whole ISO. Every such surgical edit is saved to the source tree and must prove itself on the next from-scratch build; no edit rides un-reproduced.
8. Publish to the signed mirror. The index is the signed manifest of the whole repository, so every publish regenerates and re-signs the complete index; clients verify the entire index against one signature. Data transfer is incremental, but the signed index is never partial, and the live repository is promoted by an atomic swap.
9. Promote to a stable release. A candidate is promoted to a golden release only when a full from-scratch cycle runs end to end with zero triggers — nothing required a fix. All boot and install legs are validated on representative (lower-end) hardware, with race-class items cleared over several consecutive cold boots. Anything short of that bar is a trigger: fix it in the tree and keep iterating.

The non-negotiables

• Built from source. The standard, transparent, from-source path, not opaque shortcuts.
• No silent failures. Every error surfaces; an unverified assumption becomes a checked gate or it is not trusted.
• No stubs. Placeholder code that pretends to work does not ship.
• Reproducible. Pinned, checksum-verified sources; deterministic builds.
• Only a clean build counts. A fix is done when it lives in the tree and a clean build reproduces the corrected behavior with zero manual steps.
• Signed end to end. A signed Secure-Boot chain, an integrity-verified system image, and a signed package index — verification you can check yourself.

Development setup

The build requires:

• An Ubuntu 24.04 (or equivalent) build host.
• KVM/QEMU with libvirt for VM-based builds.
• Python 3.12+ with PyYAML for the build system.
• All LFS 13.0 host requirements (run python3 scripts/host-check.py to verify).

License and sign-off

InterGenOS is licensed under the GNU General Public License v3.0 or later, the project’s outbound license. Contributions are accepted under this same license (inbound = outbound; there is no separate Contributor License Agreement).

The contributor authorship and right-to-submit attestation is the Developer Certificate of Origin (DCO), revision 1.1. By appending a Signed-off-by: trailer to each commit, you certify the DCO statements; the verbatim text lives in the repository’s DCO.md.

git commit -s

The -s (or --signoff) flag adds the trailer automatically using your user.name and user.email git configuration. Every commit in a pull request must carry the trailer; pull requests whose commits are not all signed off will fail the public-content + DCO audit workflow and cannot merge until the trailer is added.

To add the trailer to existing commits retroactively:

git rebase --signoff master    # all commits on this branch
git commit --amend --signoff   # the latest commit only

Commits made before 2026-05-18 (when the DCO was adopted) are grandfathered under the prior model; the DCO applies from that date forward.

Where to go next

• New to the system? Read the FAQ.
• Installing InterGenOS? See the Forge installer guide.