nixpkgs/docs/guides/development-workflow.md

Development Workflow Guide

Development, testing, and contribution workflow for m3ta-nixpkgs.

Initial Setup

Clone Repository

git clone https://code.m3ta.dev/m3tam3re/nixpkgs.git
cd nixpkgs

Enter Development Shell

# Default shell (includes linting tools)
nix develop

# Python shell
nix develop .#python

# DevOps shell
nix develop .#devops

Development Shell Tools

The default dev shell includes:

• statix - Nix linter
• deadnix - Find dead code
• alejandra - Code formatter

Workflow

1. Create Feature Branch

# Checkout main and pull latest
git checkout main
git pull

# Create feature branch
git checkout -b feature/my-new-package

2. Make Changes

# Create new package
mkdir -p pkgs/my-package
vim pkgs/my-package/default.nix

# Or modify existing package
vim pkgs/existing-package/default.nix

# Or add module
vim modules/nixos/my-module.nix

3. Format Code

# Format all files
nix fmt

# Format specific file
alejandra path/to/file.nix

Always format before committing.

4. Test Changes

Build Package

# Build specific package
nix build .#my-package

# Build all packages
nix build .#packages.x86_64-linux

Run Package

# Test if package runs
nix run .#my-package -- --help

# Or enter shell with package
nix shell .#my-package
my-package --version

Validate Flake

# Validate all outputs
nix flake check

# Show all outputs
nix flake show

Test Module

# Test NixOS configuration
sudo nixos-rebuild test --flake .#hostname

# Test Home Manager configuration
home-manager switch --flake .#username@hostname

5. Lint Code

# Enter dev shell for linting tools
nix develop

# Run statix
statix check .

# Run deadnix
deadnix .

# Fix auto-fixable issues
statix fix .

6. Commit Changes

# Stage changes
git add .

# Commit with conventional format
git commit -m "feat: add my-package for doing X"

# Commit types: feat, fix, docs, style, refactor, chore, test

7. Push and Create PR

# Push branch
git push origin feature/my-new-package

# Create PR via web interface or CLI
gh pr create --title "feat: add my-package" --body "Description of changes"

Testing Strategies

Local Testing

Test Package Build

# Build for current system
nix build .#my-package

# Build for specific system
nix build .#my-package --system aarch64-linux

# Build for macOS
nix build .#my-package --system x86_64-darwin

Test Package Functionality

# Enter shell with package
nix shell .#my-package

# Run the program
my-package --help
my-package --version

# Test with sample data
echo "test" | my-package

Test Configuration

# Test NixOS configuration
sudo nixos-rebuild test --flake .#hostname

# Test Home Manager configuration
home-manager switch --flake .#username@hostname

# Check configuration syntax
nix eval .#nixosConfigurations.hostname.config --apply builtins.attrNames

Integration Testing

Test with Real Services

# If package is a service
# 1. Add to configuration
# 2. Apply configuration
sudo nixos-rebuild switch

# 3. Test service
systemctl status my-service
journalctl -u my-service -f

# 4. Test functionality
curl http://localhost:8080

Test with Dependencies

# Build dependency chain
nix build .#my-package \
  --rebuild \
  --keep-going

# Check if dependencies are satisfied
nix path-info .#my-package --references

Continuous Integration

Pre-Commit Hook

Create .git/hooks/pre-commit:

#!/usr/bin/env bash
set -euo pipefail

# Format code
nix fmt

# Lint
statix check .
deadnix .

# Validate
nix flake check

# Test build
nix build .#your-package

Make executable:

chmod +x .git/hooks/pre-commit

Pre-Push Hook

Create .git/hooks/pre-push:

#!/usr/bin/env bash
set -euo pipefail

# Validate flake
nix flake check

# Run tests if they exist
# make test

Debugging

Build Failures

Hash Mismatch

Error: got: sha256-AAAAAAAA... expected: sha256-BBBBBB...

Solution: Copy the got hash and update package:

src = fetchFromGitHub {
  hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";  # Use actual hash
};

Dependency Not Found

Error: error: undefined variable 'somelib'

Solution: Check function arguments:

{
  lib,
  stdenv,
  fetchFromGitHub,
  somelib,  # Add this if missing
}:

Build Failed

Error: builder for '/nix/store/...' failed

Solution:

# Build with verbose output
nix build .#my-package -v --show-trace

# Check build logs
nix log .#my-package

# Enter build environment for debugging
nix shell -f .#my-package .bashInteractive

Runtime Failures

Package Not Executable

Error: error: operation not permitted

Solution: Check mainProgram in meta:

meta = with lib; {
  mainProgram = "my-app";  # Must match executable name
};

Library Not Found

Error: error while loading shared libraries: libfoo.so

Solution: Add to build inputs:

buildInputs = [someLib];

Configuration Failures

Option Not Found

Error: error: The option 'm3ta.mymodule' does not exist

Solution: Import the module:

imports = [
  m3ta-nixpkgs.nixosModules.default
];

Common Tasks

Update Package Version

# 1. Update version in package definition
vim pkgs/my-package/default.nix

# 2. Build to get new hash
nix build .#my-package

# 3. Update hash from error message

# 4. Test new version
nix run .#my-package -- --version

# 5. Commit
git commit -m "chore: update my-package to v2.0.0"

Update Dependencies

# 1. Update fetcher version/rev
vim pkgs/my-package/default.nix

# 2. Update dependencies if needed
vim pkgs/my-package/default.nix

# 3. Build and test
nix build .#my-package
nix run .#my-package -- --help

# 4. Commit
git commit -m "fix: update dependencies for my-package"

Add Tests

# 1. Add test to package
vim pkgs/my-package/default.nix

# 2. Run tests
nix build .#my-package

# 3. Verify tests pass

# 4. Commit
git commit -m "test: add tests for my-package"

Fix Linting Issues

# 1. Run linter
nix develop
statix check .

# 2. Fix issues manually or auto-fix
statix fix .

# 3. Check again
statix check .

# 4. Commit
git commit -m "style: fix linting issues"

Performance Optimization

Use Caching

# Use binary cache (if available)
nix build .#my-package --substituters https://cache.nixos.org https://your-cache.example.com

# Use local cache
nix build .#my-package --max-jobs 4

Parallel Builds

# Build multiple packages in parallel
nix build .#package1 .#package2 .#package3

Incremental Builds

# Only rebuild changed packages
nix build .#my-package --check

# Don't rebuild dependencies
nix build .#my-package --no-link

Release Process

Version Bump

# 1. Update versions as needed
vim pkgs/*/default.nix

# 2. Update CHANGELOG.md
vim CHANGELOG.md

# 3. Test all packages
nix flake check

# 4. Commit
git commit -m "chore: prepare release v1.0.0"

Tag Release

# Create tag
git tag -a v1.0.0 -m "Release v1.0.0"

# Push tag
git push origin v1.0.0

# Push with tags
git push --follow-tags

Update Flakes

Update flake lock after release:

# Update lock file
nix flake update

# Commit
git commit -m "chore: update flake lock"

Checklist

Before Committing

• Code formatted with nix fmt
• Passes statix check .
• Passes deadnix .
• Passes nix flake check
• Package builds successfully
• Package runs as expected
• Documentation updated (if needed)
• Commit message follows convention

Before Merging PR

• All tests pass
• Code review approved
• No merge conflicts
• Documentation complete
• Breaking changes documented

Resources

• Contributing Guide - Code style and guidelines
• Architecture - Understanding repository structure
• Adding Packages - Package creation guide
• Quick Start - Getting started guide