2023-08-28 Documentation team meeting notes #76

Development Documentation
1

Agenda

  • Discuss outline for nix.dev

Outline for nix.dev

Some notes and ideas

  • Contributing intro should move to public contributing to docs (or nix.dev) page
    • The Diataxis interpretation should have its own page
  • High-level outline should be either on the front page or categorise the side bar
  • Set up a development environment is somewhat Python-specific and has a lot of overlap with the declarative shell tutorial, but reads like a recipe. We should move it to the language-specific guides.
    • @alejandrosame: should go together with Nixpkgs Python FAQ/Guides towards nix.dev
  • Declarative shell environments would benefit from listing improvements over the command-line approach (as in Declarative and reproducible developer environments) rather then framing the previous approach as inefficient.
  • We should absolutely introduce the Nix language gently in the declarative shell tutorial and refer to the full Nix language basics for details.
  • We should at least use release branches in expressions consistently to ensure a reasonable degree of reproducibility. Stop doing <nixpkgs>
  • All of that needs to be accompanied by a broad collection of concise recipes, and a deep collection of explanations that build up Nix from first principles (possibly encompassing a complete rework and extension of the Pills); but this is longer-term thinking

Tutorials

  • Temporary environments

    • Ad hoc shell environments
    • Reproducible interpreted scripts
    • Declarative shell environments with shell.nix
      • Merge the two articles into one

  • Nix language basics

    • This is required to deal with more involved examples
    • Will probably need revised introduction to pick up on what we have seen so far

  • Using, customising, and creating packages

    • Customise packages with override and overrideAttrs
      • Take a peek into how packages are functions that call mkDerivation and defer to Packaging existing software and, as a prerequisite, Nix language basics
      • Refer to search.nixos.org and show how to find the package declaration
      • Show overriding a package parameter, such as Tor Browser with media (but ideally something that needs less time to compile)
      • Show overriding a package version, and escalate to adding patches or adjusting build phases
    • Packaging existing software
      • At the end the tutorial we should refer to the list of language-specific build helpers
        • Once we have a collection of recipes, link to those, too
      • You should get pretty far with what you have up to now, and everything else gets into convenience, scaling up, and more advanced use cases.

  • Declarative user environments and system configurations

    • Declarative user environments with Home Manager
      • Add direnv for convenience
      • The challenge here is installing Home Manager itself declaratively, but there are ways.
    • Dependency management with niv
      • This can be nicely motivated by requiring multiple remote Nix expressions
      • Now that we have Home Manager, we can seamlessly include niv in the user environment
    • Editor configuration with Home manager
      • vim with configuration and plugins
      • emacs
      • VSCode
      • Link to a few relevant configuration topics as follow-ups: Git, SSH, …
    • NixOS in a virtual machine
      • This should be motivated by some relevant system service, i.e. something that cannot be configured through Home Manager
      • The tutorial should frame NixOS as an advanced use case and offer the VM approach as a gentle introduction. It should also note that you have to figure out yourself how to translate the generic instructions to NixOS.
        • This is a compromise to account for the fact that NixOS documentation is essentially unmaintained.
    • Install NixOS
      • This should also link to nix-darwin as a native alternative for macOS, and note the support status
    • Using NixOS modules
      • Refactor your NixOS configuration
    • Build a bootable NixOS ISO image
    • Custom NixOS modules
      • Essentially import the Writing Modules section from the NixOS manual

  • Building, testing, and deploying software

    • Set up a cache
    • Set up distributed builds
    • Cross compilation
    • Continuous Integration with GitHub Actions
    • Building and running NixOS containers
    • Building and running Docker images
    • Building and running virtual machines in NixOS
    • Integration testing with NixOS virtual machines
    • Deploy NixOS images with Terraform

  • Debugging builds

  • Debugging Nix expressions

Recipes

  • Best practices
  • Pinning Nixpkgs
    • Should be expanded with an introduction and some more details on when to use what
  • Combining multiple Nixpkgs releases
    • Essentially this Discourse reply but also for Home manager and shell environments
    • Link to Dependency management with niv
  • Sharing dependencies between default.nix and shell.nix
    • Maybe this is not worth a whole tutorial
    • Alternatively it could be nested under the packaging chapter
  • Troubleshooting
    • Essentially FAQ, but of practical nature; different name to disambiguate

Reference

  • Recommended support tools
    • This can also house a section for commercial offers
  • Recommended reading
    • This should be populated from the documentation survey
  • Glossary

Concepts

  • Flakes
  • Frequently Asked Questions
    • Only conceptual!
2 Likes