nixos/docs/README-unstable and stable packages.md

Hybrid Package Management: Stable + Unstable

This NixOS configuration uses a hybrid approach where the system runs on the stable NixOS 24.05 branch but can selectively use packages from the unstable branch when needed.

How It Works

The flake.nix includes both stable and unstable nixpkgs inputs:

inputs = {
  nixpkgs.url = "nixpkgs/nixos-24.05";           # Stable base
  nixpkgs-unstable.url = "nixpkgs/nixos-unstable"; # Unstable packages
  # ... other inputs
};

The unstable packages are made available to all system configurations via specialArgs:

nixosConfigurations = {
  framework = nixpkgs.lib.nixosSystem {
    system = "x86_64-linux";
    specialArgs = {
      pkgs-unstable = import nixpkgs-unstable {
        system = "x86_64-linux";
        config.allowUnfree = true;
      };
    };
    modules = [ /* ... */ ];
  };
};

Using Unstable Packages

In System Configuration Files

To use an unstable package in any .nix configuration file:

1. Add pkgs-unstable to the function parameters:

   { config, pkgs, pkgs-unstable, ... }:
   

2. Use the unstable package:

   environment.systemPackages = with pkgs; [
     # Stable packages
     firefox
     git
   
     # Unstable packages
     pkgs-unstable.windsurf
     pkgs-unstable.some-other-package
   ];
   

Example: Current Usage

See desktop/dev.nix for a working example:

{ config, pkgs, pkgs-unstable, ... }:

{
  environment.systemPackages = with pkgs; [
    # Stable packages
    nodejs
    rpi-imager
    
    # Unstable packages
    pkgs-unstable.windsurf  # Use windsurf from unstable
  ];
}

When to Use Unstable Packages

Use unstable packages when:

• A package is not available in the stable branch
• You need a newer version with specific features or bug fixes
• You're developing with cutting-edge tools

Benefits of This Approach

1. System Stability: Core system components use stable, well-tested packages
2. Package Availability: Access to the latest packages when needed
3. Selective Updates: Choose which packages to get from unstable
4. Easy Maintenance: Clear separation between stable and unstable dependencies

Adding New Unstable Packages

To add a new unstable package:

1. Find the configuration file where you want to add the package
2. Ensure the file accepts pkgs-unstable parameter
3. Add pkgs-unstable.package-name to the appropriate list
4. Test with nixos-rebuild dry-run --flake .#framework
5. Apply with nixos-rebuild switch --flake .#framework

Updating Packages

• Stable packages: Updated when you update the flake lock
• Unstable packages: Updated when you run nix flake update

To update only unstable packages:

nix flake lock --update-input nixpkgs-unstable

Current Unstable Packages in Use

• windsurf - Modern code editor (in desktop/dev.nix)

---

This hybrid approach gives you the stability of NixOS stable with the flexibility to use cutting-edge packages when needed.