Contributor Roadmap

Suggested reading order for packaging, NixOS modules, and upstream contribution. Skips day-2 ops; follow the Operator path for that. This page is a curated reading order only — no runnable example.

Goals

• Write and review Nix confidently enough to land packages and modules
• Navigate nixpkgs layout, contribution norms, and CI/review expectations
• Author and upstream NixOS modules; use flakes as a development and delivery workflow
• Know which evaluator/features/RFCs matter before you depend on them

Prerequisites

• Comfortable with a shell and git (branches, PRs, rebases)
• Have run Nix or NixOS at least once (install or rebuild). If not, skim Beginner first
• Optional but useful: one language you will package (Python, Node, Rust, Go, …)

Reading order

1. Mental model (light)

• Why Nix, purity and reproducibility, hermetic builds
• Core vocabulary: derivation, closure, fixed-output derivation, import from derivation, overlay vs override, flake

2. Language

• Hub: Language
• Syntax and evaluation: functions, lists and attrsets, laziness, scoping and shadowing, evaluation model, purity boundaries
• Idioms used in nixpkgs: callPackage, overlays pattern, lib helpers, anti-patterns
• Quick ref: language cheatsheet or 03-language/cheatsheet

3. Store and build surface

• Builders and sandboxes, build phases, hashing and inputs, debugging builds
• Trust context when reviewing: supply chain, signing and caches, reproducible builds audit

4. nixpkgs packaging and contribution

• Hub: nixpkgs
• Architecture: stdenv, mkDerivation, package sets, lib, maintainers and teams
• Packaging: simple package, fetchers and pinning, patches and overrides, multiple outputs, language ecosystems, tests and passthru, cross-compilation
• Local iteration: writing overlays, pinning
• Upstream process: contribution — review process, ofborg and CI, staging and branches

5. NixOS modules (authoring, not operating)

• Architecture: module system, module system internals (freeformType / evalModules), options and types, config vs options
• Writing: writing a module, mkIf / mkMerge / mkOrder, custom options, assertions and warnings, upstreaming modules
• Patterns: service patterns, NixOS options cheatsheet
• Related ecosystems: Home Manager modules, module ecosystems overview

6. Flakes as contributor workflow

• Schema: flake.nix schema, inputs and outputs, lockfile, follows and overrides
• Outputs you will ship or test: packages / apps / devShells, checks and hydraJobs, templates, nixosConfigurations
• Eval rules: pure eval and impure; CLI: nix flake
• Context: flakes vs channels

7. Experimental features (awareness)

• Feature flags overview, nix-command, flakes
• Packaging-adjacent: ca-derivations, dynamic derivations, fetch-tree and git, pipe operators
• Stabilization tracking: tracking stabilization, experimental backlog

8. Dev tooling for contribution

• Shells and direnv, language toolchains, CI with Nix, testing NixOS VM tests, debugging evaluation, lazy trees and eval perf
• Editor support: LSP and IDE; formatters: alejandra / nixpkgs-fmt
• Optional (GPU/ML packaging): CUDA, ROCm, and ML stacks

9. History, governance, and implementations

• Timeline, NixOS Foundation, RFC process, release cadence, forks and governance splits
• Evaluators: cpp Nix, Lix, Tvix, Snix
• Frameworks you may meet in the wild: flake-parts, community frameworks

Scenario paths (pick one track)

First nixpkgs package PR — simple package + example corpus → packaging builders cheatsheet → custom package and overlay flake (worked example) → fetchers and pinning → language builders (Python/Node/Rust/Go, Haskell, JVM/PHP/others as needed) → tests and passthru → ofborg and CI → review process.

NixOS module upstream — writing a module + minimal-module.nix → module system internals when merge/specialArgs bite → custom options → service patterns → upstreaming modules.

Flake library / devShell — flake.nix schema + hello-flake → project devShell and direnv (worked example) → packages / apps / devShells → checks and hydraJobs → CI with Nix → Flake CI with GitHub Actions (worked example).

Private inputs in CI — access tokens → private flakes and CI → config repo layout when the flake is a fleet mono-repo.

Debugging eval failures — scoping and shadowing → laziness → purity boundaries → pure eval and impure → debugging evaluation → FAQ: common errors.

Hash / fetch breakage — fixed-output derivation + fod-fetchurl.nix → debugging builds → fetchers and pinning.

Experimental feature in a PR — feature flags overview → specific leaf (e.g. ca-derivations) → tracking stabilization; stamp behavior in commit message / PR text.

Example corpus (shared fixtures)

Reusable snippets under meta/examples/ — cite from your docs/PRs; not a second tutorial track. Multi-file walkthroughs: 16-configuration-examples. Validate fixtures locally when Nix is installed: node meta/examples/validate.mjs.

Next steps

• Pick one concrete contribution: a package bump/add, a module fix, or an RFC comment — then work the relevant scenario path above as a checklist
• Shared snippets: meta/examples (hello-flake, overlay-snippet, minimal-module, …)
• Eval/build symptom shortcuts: FAQ: common errors (IFD, FOD hash mismatch, pure-eval failures)
• Ask upstream after a minimal repro: Getting help and community
• Use glossary when terms collide; track wiki gaps in todo-coverage
• Switch to Operator only if you need install/rebuild/maintenance order, not for packaging or module design

See also

• Learning roadmaps — path chooser
• Beginner — first-pass philosophy, concepts, and a working system
• Operator — day-2 rebuild, deploy, and trust ops
• Upstream entry points (via leaf refs): nixpkgs contribution, RFC process
• Import from derivation — eval cost when packaging or reviewing flakes
• Example corpus · Configuration examples · FAQ: common errors