Commit 95f0085c7914

@@ -0,0 +1,514 @@
+# Add Package Workflow
+
+Add new packages to NixOS/nixpkgs repository.
+
+## When to Use
+
+- "add package to nixpkgs"
+- "create new nixpkgs package"
+- "package new application"
+- "init package in nixpkgs"
+
+## Quick Reference
+
+### Complete Workflow
+```bash
+# 1. Create branch
+git checkout -b pkg/package-name
+
+# 2. Create package in pkgs/by-name
+mkdir -p pkgs/by-name/pa/package-name
+vim pkgs/by-name/pa/package-name/package.nix
+
+# 3. Build and test
+nix-build -A package-name
+./result/bin/package-name
+
+# 4. Review with nixpkgs-review
+nixpkgs-review wip
+
+# 5. Format code
+nixfmt pkgs/by-name/pa/package-name/package.nix
+
+# 6. Commit and push
+git add .
+git commit -s -m "package-name: init at 1.0.0"
+git push -u origin pkg/package-name
+
+# 7. Create PR
+gh pr create
+```
+
+## Package Location
+
+### Use pkgs/by-name (Preferred)
+
+For top-level packages:
+
+```
+pkgs/by-name/
+  pa/package-name/package.nix
+```
+
+**Rules:**
+- Use first 2 letters of package name as directory prefix
+- Package directory name = attribute name
+- File must be named `package.nix`
+- Automatically included (no all-packages.nix change needed)
+
+**Examples:**
+```
+pkgs/by-name/he/hello/package.nix          # hello package
+pkgs/by-name/fi/firefox/package.nix        # firefox package
+pkgs/by-name/go/go/package.nix             # go package
+pkgs/by-name/my/my-tool/package.nix        # my-tool package
+```
+
+### Traditional Structure
+
+For packages in specialized sets or categories:
+
+```
+pkgs/
+  applications/          # GUI applications
+  development/           # Development tools
+    libraries/           # Libraries
+    tools/               # Build tools
+  servers/               # Server software
+  tools/                 # Command-line tools
+    networking/          # Network tools
+    system/              # System tools
+```
+
+**When to use:**
+- Python packages: `pkgs/development/python-modules/`
+- Perl modules: `pkgs/development/perl-modules/`
+- Node packages: Generated via `node2nix`
+- Haskell packages: Generated via `cabal2nix`
+
+## Package Template
+
+### Basic Package Structure
+
+```nix
+# pkgs/by-name/pa/package-name/package.nix
+{
+  lib,
+  stdenv,
+  fetchFromGitHub,
+  # Add build dependencies here
+}:
+
+stdenv.mkDerivation rec {
+  pname = "package-name";
+  version = "1.0.0";
+
+  src = fetchFromGitHub {
+    owner = "owner";
+    repo = "repo";
+    rev = "v${version}";
+    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+  };
+
+  nativeBuildInputs = [
+    # Build-time dependencies (compilers, build tools)
+  ];
+
+  buildInputs = [
+    # Runtime dependencies (libraries)
+  ];
+
+  meta = with lib; {
+    description = "Brief description of what this package does";
+    homepage = "https://github.com/owner/repo";
+    license = licenses.mit;
+    maintainers = with maintainers; [ your-github-username ];
+    platforms = platforms.linux;
+    mainProgram = "package-name";
+  };
+}
+```
+
+## Language-Specific Builders
+
+### Go Package (buildGoModule)
+
+```nix
+{
+  lib,
+  buildGoModule,
+  fetchFromGitHub,
+}:
+
+buildGoModule rec {
+  pname = "package-name";
+  version = "1.0.0";
+
+  src = fetchFromGitHub {
+    owner = "owner";
+    repo = "repo";
+    rev = "v${version}";
+    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+  };
+
+  vendorHash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";
+
+  ldflags = [
+    "-s"
+    "-w"
+    "-X main.version=${version}"
+  ];
+
+  meta = with lib; {
+    description = "Description of Go package";
+    homepage = "https://github.com/owner/repo";
+    license = licenses.mit;
+    maintainers = with maintainers; [ your-github-username ];
+    mainProgram = "package-name";
+  };
+}
+```
+
+**Getting vendorHash:**
+```bash
+# Use fake hash first
+vendorHash = lib.fakeHash;
+
+# Build will fail and show correct hash
+nix-build -A package-name
+# Copy hash from error message
+```
+
+### Rust Package (rustPlatform)
+
+```nix
+{
+  lib,
+  rustPlatform,
+  fetchFromGitHub,
+}:
+
+rustPlatform.buildRustPackage rec {
+  pname = "package-name";
+  version = "1.0.0";
+
+  src = fetchFromGitHub {
+    owner = "owner";
+    repo = "repo";
+    rev = "v${version}";
+    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+  };
+
+  cargoHash = "sha256-CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=";
+
+  meta = with lib; {
+    description = "Description of Rust package";
+    homepage = "https://github.com/owner/repo";
+    license = licenses.mit;
+    maintainers = with maintainers; [ your-github-username ];
+    mainProgram = "package-name";
+  };
+}
+```
+
+### Python Package (buildPythonPackage)
+
+**Note:** Python packages go in `pkgs/development/python-modules/`
+
+```nix
+{
+  lib,
+  buildPythonPackage,
+  fetchPypi,
+  setuptools,
+  wheel,
+  # Test dependencies
+  pytestCheckHook,
+}:
+
+buildPythonPackage rec {
+  pname = "package-name";
+  version = "1.0.0";
+  format = "pyproject";
+
+  src = fetchPypi {
+    inherit pname version;
+    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+  };
+
+  nativeBuildInputs = [
+    setuptools
+    wheel
+  ];
+
+  propagatedBuildInputs = [
+    # Python runtime dependencies
+  ];
+
+  nativeCheckInputs = [
+    pytestCheckHook
+  ];
+
+  pythonImportsCheck = [ "package_name" ];
+
+  meta = with lib; {
+    description = "Description of Python package";
+    homepage = "https://github.com/owner/repo";
+    license = licenses.mit;
+    maintainers = with maintainers; [ your-github-username ];
+  };
+}
+```
+
+### Node Package
+
+Node packages are typically generated using `node2nix`. See nixpkgs documentation for details.
+
+## Getting Source Hash
+
+### From GitHub
+
+```bash
+# Using nix-prefetch-github
+nix-prefetch-github owner repo --rev v1.0.0
+
+# Manual with nix-prefetch-url
+nix-prefetch-url --unpack https://github.com/owner/repo/archive/v1.0.0.tar.gz
+```
+
+### From URL
+
+```bash
+# Prefetch tarball
+nix-prefetch-url https://example.com/package-1.0.0.tar.gz
+
+# For git repositories
+nix-prefetch-git https://git.example.com/repo.git --rev v1.0.0
+```
+
+### Using Fake Hash
+
+```nix
+src = fetchFromGitHub {
+  owner = "owner";
+  repo = "repo";
+  rev = "v1.0.0";
+  hash = lib.fakeHash;  # Use fake hash
+};
+```
+
+Build will fail with correct hash:
+```
+error: hash mismatch in fixed-output derivation
+  specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+     got:    sha256-RealHashGoesHere...
+```
+
+Copy the "got:" hash.
+
+## Build and Test
+
+### Build Package
+
+```bash
+# Build package
+nix-build -A package-name
+
+# Result symlink created
+ls -l result/
+
+# Test binary
+./result/bin/package-name --version
+./result/bin/package-name --help
+```
+
+### Test Installation
+
+```bash
+# Install to profile
+nix-env -f . -iA package-name
+
+# Or with nix profile
+nix profile install .#package-name
+
+# Test installed version
+package-name --version
+```
+
+### Run Tests
+
+```bash
+# Tests run automatically during build if doCheck = true
+nix-build -A package-name
+
+# To debug test failures
+nix-build -A package-name --keep-failed
+cd /tmp/nix-build-*
+# Examine test output
+```
+
+## Review with nixpkgs-review
+
+```bash
+# Review your changes
+nixpkgs-review wip
+
+# This will:
+# 1. Build your new package
+# 2. Build packages that depend on it
+# 3. Drop you into nix-shell
+# 4. Test the package
+
+# In nix-shell
+package-name --version
+package-name --help
+
+# Exit when satisfied
+exit
+```
+
+## Format Code
+
+```bash
+# Format Nix file
+nixfmt pkgs/by-name/pa/package-name/package.nix
+
+# Or format all changed files
+nixfmt $(git diff --name-only '*.nix')
+```
+
+## Commit Message Format
+
+### New Package
+
+```
+package-name: init at 1.0.0
+```
+
+### New Package with Details
+
+```
+package-name: init at 1.0.0
+
+Package description and why it's useful.
+
+Closes #12345
+```
+
+### Python Package
+
+```
+python3Packages.package-name: init at 1.0.0
+```
+
+## Create Pull Request
+
+### Push Branch
+
+```bash
+# Push to your fork
+git push -u origin pkg/package-name
+```
+
+### Create PR with GitHub CLI
+
+```bash
+# Create PR
+gh pr create
+
+# Fill in:
+# Title: package-name: init at 1.0.0
+# Description: What the package does, why it's useful
+```
+
+### PR Description Template
+
+```markdown
+## Description
+Brief description of what this package does.
+
+## Checklist
+- [ ] Built and tested locally
+- [ ] Ran nixpkgs-review
+- [ ] Formatted with nixfmt
+- [ ] Meta attributes complete (description, license, maintainers)
+- [ ] mainProgram set (if applicable)
+
+## Testing
+Tested on x86_64-linux:
+- [x] Builds successfully
+- [x] Binary executes
+- [x] --help and --version work
+```
+
+## Checklist
+
+Before submitting PR:
+
+- [ ] Package builds successfully (`nix-build -A package-name`)
+- [ ] Binary works (`./result/bin/package-name`)
+- [ ] Ran `nixpkgs-review wip`
+- [ ] Formatted with `nixfmt`
+- [ ] Used `pkgs/by-name` structure (if top-level package)
+- [ ] Correct package name (lowercase, hyphens)
+- [ ] Accurate description
+- [ ] Correct license
+- [ ] Added yourself to maintainers
+- [ ] Set `mainProgram` (if applicable)
+- [ ] Commit message follows convention
+- [ ] Signed commit (`-s` flag)
+
+## Common Issues
+
+### Package Name
+
+- Use lowercase
+- Use hyphens, not underscores
+- Match upstream name when possible
+- Don't include language prefix (no "python-", "go-", etc.)
+
+### Dependencies
+
+**nativeBuildInputs** (build-time):
+- Compilers (gcc, rustc)
+- Build tools (cmake, meson, pkg-config)
+- Code generators
+
+**buildInputs** (runtime):
+- Libraries (openssl, zlib)
+- Runtime dependencies
+
+**propagatedBuildInputs** (dependencies that must be in runtime environment):
+- Libraries that expose headers
+- Python dependencies
+
+### License
+
+Find license in upstream repository:
+
+```nix
+# Common licenses
+licenses.mit
+licenses.asl20        # Apache 2.0
+licenses.gpl3Only
+licenses.lgpl3Only
+licenses.bsd3
+licenses.mpl20        # Mozilla Public License 2.0
+```
+
+### Platforms
+
+```nix
+# Common platform sets
+platforms.linux
+platforms.darwin
+platforms.unix        # Linux + macOS
+platforms.all
+```
+
+## Resources
+
+- [Nixpkgs Manual - Quick Start](https://nixos.org/manual/nixpkgs/stable/#chap-quick-start)
+- [pkgs/by-name README](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/README.md)
+- [Package Naming](https://nixos.org/manual/nixpkgs/stable/#sec-package-naming)
+- [Contributing to Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md)

@@ -0,0 +1,615 @@
+# Fix Package Workflow
+
+Fix broken or failing packages in NixOS/nixpkgs.
+
+## When to Use
+
+- "fix broken package"
+- "package build failing"
+- "fix nixpkgs package"
+- "package doesn't work"
+
+## Quick Reference
+
+### Fix Workflow
+
+```bash
+# 1. Create branch
+git checkout -b fix/package-name-issue
+
+# 2. Identify the problem
+nix-build -A package-name --keep-failed
+cd /tmp/nix-build-*
+# Examine error
+
+# 3. Fix package
+vim pkgs/by-name/pa/package-name/package.nix
+
+# 4. Test fix
+nix-build -A package-name
+./result/bin/package-name
+
+# 5. Review
+nixpkgs-review wip
+
+# 6. Commit
+git add .
+git commit -s -m "package-name: fix build on aarch64-linux"
+
+# 7. Push and create PR
+git push -u origin fix/package-name-issue
+gh pr create
+```
+
+## Identifying Issues
+
+### Check Build Status
+
+```bash
+# Try building
+nix-build -A package-name
+
+# Keep failed build directory
+nix-build -A package-name --keep-failed
+
+# View full build log
+nix log --extra-experimental-features nix-command .#package-name
+```
+
+### Common Error Sources
+
+1. **Build failures** - compilation errors, missing dependencies
+2. **Test failures** - failing test suites
+3. **Runtime failures** - package builds but doesn't execute
+4. **Platform-specific** - works on x86_64 but not aarch64
+5. **Hash mismatches** - upstream changed tarball
+6. **Dependency conflicts** - incompatible with other packages
+
+## Common Fixes
+
+### Missing Dependencies
+
+**Error:**
+```
+error: foo.h: No such file or directory
+error: cannot find -lfoo
+Package 'foo' not found
+```
+
+**Fix:**
+```nix
+# Add missing dependency
+buildInputs = [
+  existingDep
+  foo  # Add the missing library
+];
+
+# For build tools
+nativeBuildInputs = [
+  pkg-config  # Often needed to find libraries
+  cmake
+];
+```
+
+### Wrong Dependency Type
+
+```nix
+# Build-time only (compilers, build tools)
+nativeBuildInputs = [
+  cmake
+  pkg-config
+  makeWrapper
+];
+
+# Runtime (libraries, executables)
+buildInputs = [
+  openssl
+  zlib
+  ncurses
+];
+
+# Libraries that expose headers
+propagatedBuildInputs = [
+  libfoo
+];
+```
+
+### Test Failures
+
+**Option 1: Disable all tests**
+```nix
+# Quick workaround
+doCheck = false;
+```
+
+**Option 2: Skip specific failing tests**
+```nix
+checkPhase = ''
+  runHook preCheck
+
+  # Skip known failing test
+  pytest -k "not test_that_fails"
+
+  # Or for Go
+  go test -skip="TestThatFails" ./...
+
+  runHook postCheck
+'';
+```
+
+**Option 3: Fix test environment**
+```nix
+preCheck = ''
+  # Set up test environment
+  export HOME=$TMPDIR
+  export PATH=$PATH:${lib.makeBinPath [ git ]}
+'';
+
+nativeCheckInputs = [
+  pytestCheckHook  # Python tests
+  git  # Often needed by tests
+];
+```
+
+### Platform-Specific Fixes
+
+**Broken on specific platform:**
+```nix
+meta = with lib; {
+  # Mark as broken on platform
+  broken = stdenv.isDarwin;  # Broken on macOS
+  broken = stdenv.isAarch64; # Broken on ARM
+
+  # Or limit to specific platforms
+  platforms = platforms.linux;  # Linux only
+  platforms = [ "x86_64-linux" ];  # x86_64 Linux only
+};
+```
+
+**Conditional dependencies:**
+```nix
+buildInputs = [
+  commonDep
+] ++ lib.optionals stdenv.isLinux [
+  linuxOnlyDep
+] ++ lib.optionals stdenv.isDarwin [
+  darwinOnlyDep
+];
+```
+
+### Hash Mismatch
+
+**Error:**
+```
+error: hash mismatch in fixed-output derivation
+  specified: sha256-AAAA...
+     got:    sha256-BBBB...
+```
+
+**Fix:**
+```nix
+# Update to correct hash
+src = fetchFromGitHub {
+  owner = "owner";
+  repo = "repo";
+  rev = "v${version}";
+  hash = "sha256-BBBB...";  # Use hash from error message
+};
+```
+
+**If upstream changed tarball without version bump:**
+```nix
+# Document the issue
+# Sometimes maintainers change release tarballs
+# In this case, update hash and note in commit message
+```
+
+### Missing Files in Output
+
+**Error:**
+Package builds but files missing from `result/`
+
+**Fix:**
+```nix
+installPhase = ''
+  runHook preInstall
+
+  # Ensure directories exist
+  mkdir -p $out/bin
+  mkdir -p $out/share/man/man1
+
+  # Install files explicitly
+  cp myapp $out/bin/
+  cp myapp.1 $out/share/man/man1/
+
+  runHook postInstall
+'';
+```
+
+### Library Not Found at Runtime
+
+**Error:**
+```
+error while loading shared libraries: libfoo.so.1: cannot open shared object file
+```
+
+**Fix:**
+```nix
+# Add autoPatchelfHook
+nativeBuildInputs = [
+  autoPatchelfHook
+];
+
+buildInputs = [
+  libfoo  # Ensure library is in buildInputs
+];
+
+# Or manually patch
+postInstall = ''
+  patchelf --set-rpath ${lib.makeLibraryPath [ libfoo ]} $out/bin/myapp
+'';
+```
+
+### Hardcoded Paths
+
+**Error:**
+```
+/bin/sh: not found
+/usr/bin/env: not found
+```
+
+**Fix:**
+```nix
+postPatch = ''
+  # Replace hardcoded paths
+  substituteInPlace script.sh \
+    --replace '/bin/sh' '${stdenv.shell}' \
+    --replace '/usr/bin/env' '${coreutils}/bin/env'
+
+  # For Python scripts
+  substituteInPlace script.py \
+    --replace '/usr/bin/env python' '${python3}/bin/python3'
+'';
+```
+
+## Applying Patches
+
+### Create Patch File
+
+```bash
+# Make changes in package source
+cd /tmp/nix-build-package-*/
+# Edit files
+git diff > fix-build.patch
+cp fix-build.patch ~/nixpkgs/pkgs/by-name/pa/package-name/
+```
+
+### Apply Patch
+
+```nix
+{
+  # ...
+  patches = [
+    ./fix-build.patch
+    ./another-fix.patch
+  ];
+}
+```
+
+### Fetch Patch from URL
+
+```nix
+{
+  patches = [
+    # Fetch patch from upstream PR
+    (fetchpatch {
+      url = "https://github.com/owner/repo/commit/abc123.patch";
+      hash = "sha256-...";
+    })
+  ];
+}
+```
+
+## Advanced Fixes
+
+### Override Build Phase
+
+```nix
+buildPhase = ''
+  runHook preBuild
+
+  # Custom build commands
+  make -j$NIX_BUILD_CORES CUSTOM_FLAG=1
+
+  runHook postBuild
+'';
+```
+
+### Fix CMake/Meson Issues
+
+```nix
+# CMake
+cmakeFlags = [
+  "-DENABLE_TESTS=OFF"
+  "-DUSE_SYSTEM_LIB=ON"
+];
+
+# Meson
+mesonFlags = [
+  "-Dtests=false"
+  "-Dsystemd=true"
+];
+```
+
+### Environment Variables
+
+```nix
+# Set environment for build
+env = {
+  NIX_CFLAGS_COMPILE = "-O2";
+  GOFLAGS = "-tags=nogui";
+};
+
+# Or old style
+NIX_CFLAGS_COMPILE = "-O2";
+```
+
+### Wrapper Scripts
+
+```nix
+postInstall = ''
+  # Wrap binary to set environment
+  wrapProgram $out/bin/myapp \
+    --set CONFIG_DIR "$out/share/config" \
+    --prefix PATH : ${lib.makeBinPath [ dependency ]}
+'';
+
+nativeBuildInputs = [ makeWrapper ];
+```
+
+## Testing Fixes
+
+### Build Package
+
+```bash
+# Build fixed package
+nix-build -A package-name
+
+# Check outputs
+ls -R result/
+
+# Test binary
+./result/bin/package-name --version
+./result/bin/package-name --help
+```
+
+### Test on Multiple Platforms
+
+```bash
+# Build for aarch64
+nix-build -A package-name --system aarch64-linux
+
+# Or use nixpkgs-review with system flag
+nixpkgs-review wip --system x86_64-linux,aarch64-linux
+```
+
+### Run Tests
+
+```bash
+# Enable tests
+nix-build -A package-name --arg doCheck true
+
+# Or temporarily in package
+doCheck = true;
+```
+
+### Check Dependents
+
+```bash
+# Ensure fix doesn't break dependents
+nixpkgs-review wip
+
+# This builds all packages that depend on the fixed package
+```
+
+## Commit Message Format
+
+### Simple Fix
+
+```
+package-name: fix build on aarch64-linux
+```
+
+### Fix with Details
+
+```
+package-name: fix build failure
+
+The build was failing due to missing libfoo dependency.
+Added libfoo to buildInputs to fix compilation.
+
+Fixes #12345
+```
+
+### Platform-Specific Fix
+
+```
+package-name: fix build on darwin
+
+- Add CoreFoundation to buildInputs
+- Disable failing tests on macOS
+- Patch hardcoded /bin/sh paths
+```
+
+### Test Fix
+
+```
+package-name: disable failing tests
+
+Tests fail in sandbox environment due to network access.
+Disabled network-dependent tests while keeping others.
+
+See: https://github.com/owner/repo/issues/123
+```
+
+## Creating Pull Request
+
+```bash
+# Push fix
+git push -u origin fix/package-name-issue
+
+# Create PR
+gh pr create
+
+# Title: package-name: fix build on aarch64-linux
+# Reference issue if applicable
+```
+
+### PR Description Template
+
+```markdown
+## Problem
+Package fails to build on aarch64-linux with error:
+```
+error message here
+```
+
+## Solution
+Added missing `libfoo` dependency to `buildInputs`.
+
+## Testing
+- [x] Builds successfully on x86_64-linux
+- [x] Builds successfully on aarch64-linux
+- [x] Binary executes
+- [x] Tests pass
+- [x] Ran nixpkgs-review (no breakages)
+
+Fixes #12345
+```
+
+## Debugging Tips
+
+### View Full Build Output
+
+```bash
+# More verbose
+nix-build -A package-name -v
+
+# Keep failed build
+nix-build -A package-name --keep-failed
+
+# Show trace
+nix-build -A package-name --show-trace
+```
+
+### Inspect Build Environment
+
+```bash
+# Enter build environment
+nix-shell '<nixpkgs>' -A package-name
+
+# Now you can:
+unpackPhase
+cd $sourceRoot
+ls -la
+configurePhase
+buildPhase
+# etc.
+```
+
+### Check Dependencies
+
+```bash
+# Runtime dependencies
+ldd result/bin/program
+
+# Store path dependencies
+nix-store --query --references result/
+
+# Full dependency tree
+nix-store --query --tree result/
+```
+
+### Search for Similar Packages
+
+```bash
+# Find similar packages that might have solutions
+grep -r "similar-package" pkgs/
+
+# Look at how other packages handle the issue
+```
+
+## Common Patterns
+
+### Python Package Fixes
+
+```nix
+{
+  # Disable import check if failing
+  pythonImportsCheck = [ ];
+
+  # Or fix imports
+  pythonImportsCheck = [ "module_name" ];
+
+  # Add missing Python dependencies
+  propagatedBuildInputs = [
+    requests
+    click
+  ];
+
+  # Fix tests
+  nativeCheckInputs = [
+    pytestCheckHook
+  ];
+
+  # Skip specific tests
+  disabledTests = [
+    "test_network"  # Requires network
+    "test_failing"  # Known failure
+  ];
+}
+```
+
+### Go Package Fixes
+
+```nix
+{
+  # Update vendor hash
+  vendorHash = "sha256-...";
+
+  # Exclude vendor directory
+  excludedPackages = [ "vendor" ];
+
+  # Skip failing tests
+  checkFlags = [
+    "-skip=TestThatFails"
+  ];
+
+  # Set build tags
+  tags = [ "netgo" ];
+}
+```
+
+### Rust Package Fixes
+
+```nix
+{
+  # Update cargo hash
+  cargoHash = "sha256-...";
+
+  # Disable default features
+  buildNoDefaultFeatures = true;
+
+  # Enable specific features
+  buildFeatures = [ "feature1" "feature2" ];
+
+  # Skip tests
+  doCheck = false;
+}
+```
+
+## Resources
+
+- [Nixpkgs Manual - Debugging](https://nixos.org/manual/nixpkgs/stable/#chap-debugging)
+- [NixOS Wiki - Troubleshooting](https://nixos.wiki/wiki/Troubleshooting)
+- [Common Build Issues](https://nixos.org/manual/nixpkgs/stable/#chap-common-issues)

@@ -0,0 +1,401 @@
+# Review Workflow
+
+Review pull requests in NixOS/nixpkgs using nixpkgs-review.
+
+## When to Use
+
+- "review nixpkgs pr"
+- "nixpkgs-review pr"
+- "review pull request"
+- "test nixpkgs pr"
+
+## Quick Commands
+
+### Basic PR Review
+```bash
+# Review PR by number
+nixpkgs-review pr 12345
+
+# Review and post results to PR
+nixpkgs-review pr 12345 --post-result
+
+# Review specific packages only
+nixpkgs-review pr 12345 -p package-name
+```
+
+### Review Local Changes
+```bash
+# Review uncommitted changes
+nixpkgs-review wip
+
+# Review staged changes
+nixpkgs-review wip --staged
+
+# Review specific commit
+nixpkgs-review rev HEAD
+```
+
+## Setup
+
+### Install nixpkgs-review
+```bash
+# Run without installing
+nix run nixpkgs#nixpkgs-review
+
+# Install to profile
+nix profile install nixpkgs#nixpkgs-review
+
+# In development shell
+nix-shell -p nixpkgs-review
+```
+
+### GitHub Authentication
+Required for posting results with `--post-result`:
+
+```bash
+# Method 1: GitHub CLI (recommended)
+gh auth login
+
+# Method 2: Environment variable
+export GITHUB_TOKEN=ghp_...
+
+# Method 3: hub configuration (~/.config/hub)
+github.com:
+- user: username
+  oauth_token: token
+  protocol: https
+```
+
+## Review Workflow
+
+### Step 1: Fetch and Review PR
+```bash
+# Review PR
+nixpkgs-review pr 12345
+
+# This will:
+# 1. Fetch the PR
+# 2. Determine changed packages
+# 3. Build all changed packages
+# 4. Drop you into nix-shell with built packages
+```
+
+### Step 2: Test Built Packages
+In the nix-shell environment:
+
+```bash
+# Test the package works
+package-name --version
+package-name --help
+
+# Check binary
+which package-name
+ls -la $(which package-name)
+
+# For GUI applications
+package-name &
+
+# Check package structure
+nix build .#package-name
+tree result/
+```
+
+### Step 3: Review Changes
+While in nix-shell, examine the PR:
+
+```bash
+# View PR comments
+nixpkgs-review comments
+
+# Check file changes
+git diff master...pr-branch
+
+# Review package definition
+cat pkgs/path/to/package/default.nix
+```
+
+### Step 4: Approve or Request Changes
+```bash
+# In nix-shell: Approve if good
+nixpkgs-review approve
+
+# Exit shell
+exit
+
+# Or post results without approval
+nixpkgs-review pr 12345 --post-result
+```
+
+## What to Check
+
+### 1. Package Builds Successfully
+- No build errors
+- All outputs created
+- Dependencies resolved
+
+### 2. Tests Pass
+```bash
+# Check if tests are enabled
+nix show-derivation .#package-name | grep doCheck
+
+# Tests run during build
+# Watch for test failures in build output
+```
+
+### 3. Binary Works
+```bash
+# Can execute
+package-name --version
+
+# Shows help
+package-name --help
+
+# Runs without errors
+package-name (basic functionality test)
+```
+
+### 4. Dependencies Correct
+```bash
+# Check runtime dependencies
+ldd result/bin/package-name
+
+# Should not have missing libraries
+# Should use Nix store paths
+```
+
+### 5. Meta Attributes
+Check package metadata:
+
+```nix
+# In package definition
+meta = with lib; {
+  description = "Clear, accurate description";
+  homepage = "https://correct-url.com";
+  license = licenses.mit;  # Correct license
+  maintainers = with maintainers; [ username ];
+  platforms = platforms.linux;  # Appropriate platforms
+};
+```
+
+### 6. No Regressions
+```bash
+# Check dependent packages still build
+nixpkgs-review pr 12345  # Builds dependents automatically
+
+# Look for failed dependents in output
+```
+
+### 7. Code Quality
+- Follows Nix coding conventions
+- Uses appropriate builders (buildGoModule, rustPlatform, etc.)
+- No hardcoded paths
+- Proper use of fetchFromGitHub/fetchurl
+- Hash is correct (sha256/sha512)
+
+## Review Scenarios
+
+### Version Update PR
+```bash
+# Review version bump
+nixpkgs-review pr 12345
+
+# Check:
+# - Version number updated correctly
+# - Hash updated correctly
+# - Tests still pass
+# - No breaking changes
+# - Changelog reviewed (if major update)
+```
+
+What to verify:
+- Version matches upstream release
+- Hash is correct (not placeholder)
+- Dependencies still compatible
+- No new runtime dependencies added without documentation
+
+### New Package PR
+```bash
+# Review new package
+nixpkgs-review pr 12345 -p new-package
+
+# Check:
+# - Package name follows conventions
+# - In correct location (pkgs/by-name/ preferred)
+# - Meta attributes complete
+# - License specified correctly
+# - Maintainers added
+# - Tests included (if applicable)
+# - Description accurate
+```
+
+Package location rules:
+- Prefer `pkgs/by-name/xx/package-name/package.nix`
+- Two-letter prefix from package name
+- Must be top-level package
+- Cannot use specialized callPackage (python3Packages, etc.)
+
+### Security Update PR
+```bash
+# Review security update
+nixpkgs-review pr 12345
+
+# Check:
+# - CVE mentioned in PR description
+# - Version fixes vulnerability
+# - All variants updated (if multiple)
+# - Security advisory linked
+# - Consider backport to stable
+```
+
+### Breaking Change PR
+```bash
+# Review breaking change
+nixpkgs-review pr 12345
+
+# Check:
+# - Breaking changes documented
+# - Migration guide provided
+# - Dependents tested
+# - Release notes updated
+# - Staged appropriately (staging branch)
+```
+
+## Advanced Options
+
+### Review Specific Packages
+```bash
+# Build only specific packages
+nixpkgs-review pr 12345 -p firefox chromium
+
+# Build packages matching regex
+nixpkgs-review pr 12345 --package-regex "python.*"
+```
+
+### Cross-System Review
+```bash
+# Review for multiple systems
+nixpkgs-review pr 12345 --system x86_64-linux,aarch64-linux
+```
+
+### Non-Interactive Review
+```bash
+# Don't enter shell
+nixpkgs-review pr 12345 --no-shell
+
+# Run custom command
+nixpkgs-review pr 12345 --run "nix-shell -p hello --run hello"
+
+# Print results to stdout
+nixpkgs-review pr 12345 --print-result
+```
+
+### Sandbox Mode
+```bash
+# Protect HOME directory
+nixpkgs-review pr 12345 --sandbox
+```
+
+## Posting Results
+
+### Automatic Posting
+```bash
+# Post build report as PR comment
+nixpkgs-review pr 12345 --post-result
+
+# Requires GitHub authentication (see Setup)
+```
+
+The posted comment includes:
+- Build status (success/failure)
+- List of built packages
+- Build logs (if failed)
+- System information
+
+### Manual Comments
+If `--post-result` doesn't work:
+
+1. Note which packages built successfully
+2. Note any failures with error messages
+3. Post manual comment on PR with findings
+4. Include system (x86_64-linux, aarch64-linux, etc.)
+
+## Review Best Practices
+
+1. **Be constructive** - Focus on helping improve the PR
+2. **Test thoroughly** - Don't just check if it builds
+3. **Check license** - Ensure license matches upstream
+4. **Verify platforms** - Check claimed platforms are correct
+5. **Run the binary** - Actually execute the program
+6. **Check description** - Should be clear and accurate
+7. **Review commit message** - Should follow conventions
+8. **Check for TODOs** - Ensure no placeholder comments
+9. **Approve quickly** - Don't block good PRs unnecessarily
+10. **Be respectful** - Remember there's a human behind the PR
+
+## Common Issues
+
+### Build Failures
+```bash
+# Keep build directory on failure
+nixpkgs-review pr 12345 --keep-going
+
+# View build logs
+nix log .#package-name
+
+# Show full trace
+nixpkgs-review pr 12345 --show-trace
+```
+
+### Hash Mismatches
+Common in updates:
+
+```bash
+# Correct hash shown in error
+# Copy the "got:" hash to package definition
+hash = "sha256-AAAA...";  # Wrong
+hash = "sha256-BBBB...";  # Correct (from error)
+```
+
+### Missing Dependencies
+```bash
+# Check what's missing
+ldd result/bin/program
+
+# Add to buildInputs or nativeBuildInputs
+nativeBuildInputs = [ pkg-config ];
+buildInputs = [ libfoo ];
+```
+
+### Test Failures
+```bash
+# If tests fail but package works
+# Suggest disabling tests with comment:
+doCheck = false;
+
+# Or skip specific tests
+checkPhase = ''
+  runHook preCheck
+  pytest -k "not failing_test"
+  runHook postCheck
+'';
+```
+
+## Batch Review
+
+For reviewing multiple PRs:
+
+```bash
+# Review multiple PRs
+for pr in 12345 12346 12347; do
+  nixpkgs-review pr $pr --no-shell --post-result
+done
+
+# Or in parallel (careful with resources!)
+parallel nixpkgs-review pr {} --no-shell --post-result ::: 12345 12346 12347
+```
+
+## Resources
+
+- [nixpkgs-review](https://github.com/Mic92/nixpkgs-review)
+- [Reviewing Contributions](https://ryantm.github.io/nixpkgs/contributing/reviewing-contributions/)
+- [Nixpkgs Manual - Contributing](https://nixos.org/manual/nixpkgs/stable/#chap-contributing)

@@ -0,0 +1,535 @@
+# Update Package Workflow
+
+Update existing packages in NixOS/nixpkgs to newer versions.
+
+## When to Use
+
+- "update nixpkgs package"
+- "bump package version"
+- "upgrade package to latest"
+- "nix-update package"
+
+## Quick Reference
+
+### Automatic Update with nix-update
+
+```bash
+# 1. Create branch
+git checkout -b update/package-name
+
+# 2. Update package
+nix-update package-name
+
+# 3. Build and test
+nix-build -A package-name
+
+# 4. Review changes
+nixpkgs-review wip
+
+# 5. Commit and push
+git add .
+git commit -s -m "package-name: 1.0.0 -> 1.1.0"
+git push -u origin update/package-name
+
+# 6. Create PR
+gh pr create
+```
+
+### Manual Update
+
+```bash
+# 1. Edit package file
+vim pkgs/by-name/pa/package-name/package.nix
+
+# 2. Update version
+version = "1.1.0";  # was "1.0.0"
+
+# 3. Update hash (use fake hash first)
+hash = lib.fakeHash;
+
+# 4. Build to get correct hash
+nix-build -A package-name
+# Copy correct hash from error
+
+# 5. Test and commit
+```
+
+## Using nix-update
+
+### Install nix-update
+
+```bash
+# Run without installing
+nix run nixpkgs#nix-update
+
+# Install to profile
+nix profile install nixpkgs#nix-update
+
+# In development shell
+nix-shell -p nix-update
+```
+
+### Basic Update
+
+```bash
+# Update to latest version
+nix-update package-name
+
+# nix-update will:
+# 1. Fetch latest version from upstream
+# 2. Update version in package file
+# 3. Update source hash
+# 4. Update cargo/npm/vendor hashes if needed
+```
+
+### Update with Options
+
+```bash
+# Update and build
+nix-update --build package-name
+
+# Update and run tests
+nix-update --test package-name
+
+# Update and commit
+nix-update --commit package-name
+
+# Update, build, and commit
+nix-update --build --commit package-name
+
+# Update and format
+nix-update --format package-name
+
+# All together
+nix-update --build --test --format --commit package-name
+```
+
+### Update to Specific Version
+
+```bash
+# Update to specific version
+nix-update --version=1.2.3 package-name
+
+# Update to unstable/latest
+nix-update --version=unstable package-name
+
+# Update to branch
+nix-update --version=branch=main package-name
+```
+
+### Update Different Package Types
+
+```bash
+# Python package
+nix-update python3Packages.package-name
+
+# Go module
+nix-update package-name
+
+# Rust package
+nix-update package-name
+
+# Node package (if supported)
+nix-update nodePackages.package-name
+```
+
+## Manual Update Process
+
+### Step 1: Update Version
+
+Edit the package file:
+
+```nix
+# Before
+stdenv.mkDerivation rec {
+  pname = "package-name";
+  version = "1.0.0";
+  # ...
+}
+
+# After
+stdenv.mkDerivation rec {
+  pname = "package-name";
+  version = "1.1.0";
+  # ...
+}
+```
+
+### Step 2: Update Source Hash
+
+#### Method 1: Fake Hash
+```nix
+src = fetchFromGitHub {
+  owner = "owner";
+  repo = "repo";
+  rev = "v${version}";
+  hash = lib.fakeHash;  # Temporary fake hash
+};
+```
+
+Build to get correct hash:
+```bash
+nix-build -A package-name
+```
+
+Error will show correct hash:
+```
+error: hash mismatch in fixed-output derivation
+  specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+     got:    sha256-RealHashHere...
+```
+
+Copy the "got:" hash.
+
+#### Method 2: nix-prefetch
+```bash
+# For GitHub
+nix-prefetch-github owner repo --rev v1.1.0
+
+# For tarball
+nix-prefetch-url https://example.com/package-1.1.0.tar.gz
+
+# For git
+nix-prefetch-git https://git.example.com/repo.git --rev v1.1.0
+```
+
+### Step 3: Update Vendor Hash (Go/Rust)
+
+#### Go Packages (vendorHash)
+
+```nix
+buildGoModule rec {
+  # ...
+  vendorHash = lib.fakeHash;  # Temporary
+}
+```
+
+Build to get correct hash:
+```bash
+nix-build -A package-name
+```
+
+Copy vendor hash from error message.
+
+#### Rust Packages (cargoHash)
+
+```nix
+rustPlatform.buildRustPackage rec {
+  # ...
+  cargoHash = lib.fakeHash;  # Temporary
+}
+```
+
+Build to get correct hash.
+
+### Step 4: Check for Breaking Changes
+
+Before committing:
+
+```bash
+# Build package
+nix-build -A package-name
+
+# Test binary
+./result/bin/package-name --version
+./result/bin/package-name --help
+
+# Check changelog
+# Visit upstream repository and review CHANGELOG.md
+```
+
+### Step 5: Build Dependents
+
+```bash
+# Use nixpkgs-review to build packages that depend on this
+nixpkgs-review wip
+
+# Ensure no packages break due to update
+```
+
+## Review Changes
+
+### Use nixpkgs-review
+
+```bash
+# Review your update
+nixpkgs-review wip
+
+# This will:
+# 1. Build updated package
+# 2. Build all packages that depend on it
+# 3. Report any breakages
+# 4. Drop you into nix-shell for testing
+
+# In nix-shell
+package-name --version  # Should show new version
+package-name --help
+exit
+```
+
+### Check Diff
+
+```bash
+# View changes
+git diff
+
+# Should see:
+# - version = "1.0.0"; + version = "1.1.0";
+# - hash = "sha256-old..."; + hash = "sha256-new...";
+```
+
+## Commit Message Format
+
+### Simple Version Bump
+
+```
+package-name: 1.0.0 -> 1.1.0
+```
+
+### Version Bump with Details
+
+```
+package-name: 1.0.0 -> 1.1.0
+
+Notable changes:
+- Added new feature X
+- Fixed CVE-2024-XXXXX
+- Breaking: removed deprecated API Y
+
+Changelog: https://github.com/owner/repo/releases/tag/v1.1.0
+```
+
+### Major Version Update
+
+```
+package-name: 1.0.0 -> 2.0.0
+
+Breaking changes:
+- API changed from X to Y
+- Configuration format updated
+- Minimum Go version now 1.21
+
+Migration guide: https://...
+```
+
+### Security Update
+
+```
+package-name: 1.0.0 -> 1.0.1 (security)
+
+Fixes CVE-2024-XXXXX: Remote code execution vulnerability
+
+Security advisory: https://...
+```
+
+## Common Update Scenarios
+
+### Routine Version Update
+
+```bash
+# Automated workflow
+nix-update --build --commit package-name
+nixpkgs-review wip
+git push -u origin update/package-name
+gh pr create
+```
+
+### Major Version Update
+
+```bash
+# More careful approach
+nix-update --version=2.0.0 package-name
+nix-build -A package-name
+./result/bin/package-name  # Thorough testing
+nixpkgs-review wip  # Check all dependents
+# Review breaking changes
+git commit -s -m "package-name: 1.0 -> 2.0 (breaking changes)"
+```
+
+### Security Update
+
+```bash
+# Quick turnaround
+nix-update --version=1.0.1 package-name
+nix-build -A package-name
+nixpkgs-review wip
+git commit -s -m "package-name: 1.0.0 -> 1.0.1 (CVE-2024-XXXXX)"
+git push
+gh pr create --title "package-name: security update" --label "security"
+```
+
+### Update with Dependency Changes
+
+```bash
+# Update package
+nix-update package-name
+
+# Edit package to add new dependencies
+vim pkgs/by-name/pa/package-name/package.nix
+
+# Add new buildInputs
+buildInputs = [ oldDep newDep ];
+
+# Build and test
+nix-build -A package-name
+nixpkgs-review wip
+
+# Commit with dependency note
+git commit -s -m "package-name: 1.0.0 -> 1.1.0
+
+- Add newDep dependency for new feature
+"
+```
+
+## Python Package Updates
+
+### Update Python Package
+
+```bash
+# Python packages in pkgs/development/python-modules/
+nix-update python3Packages.package-name
+
+# Or manually
+vim pkgs/development/python-modules/package-name/default.nix
+```
+
+### Update PyPI Hash
+
+```bash
+# Use nix-prefetch-url
+nix-prefetch-url https://pypi.io/packages/source/p/package-name/package-name-1.1.0.tar.gz
+
+# Or use fake hash
+src = fetchPypi {
+  inherit pname version;
+  hash = lib.fakeHash;
+};
+```
+
+## Handling Update Failures
+
+### Build Fails After Update
+
+```bash
+# Keep build directory
+nix-build -A package-name --keep-failed
+
+# Inspect build
+cd /tmp/nix-build-package-*
+cat build.log
+
+# Common issues:
+# - New dependencies needed
+# - Build system changed
+# - Tests failing
+```
+
+### Add New Dependencies
+
+```nix
+# Add to nativeBuildInputs or buildInputs
+buildInputs = [
+  existingDep
+  newlyRequiredDep  # Added in v1.1.0
+];
+```
+
+### Disable Failing Tests
+
+```nix
+# Temporary workaround
+doCheck = false;
+
+# Or skip specific tests
+checkPhase = ''
+  runHook preCheck
+  pytest -k "not failing_test_name"
+  runHook postCheck
+'';
+```
+
+### Apply Patches
+
+```nix
+# Add patch for nixpkgs-specific fixes
+patches = [
+  ./fix-build-on-nix.patch
+];
+```
+
+## Checklist
+
+Before submitting update PR:
+
+- [ ] Package builds successfully
+- [ ] Binary executes and shows new version
+- [ ] Ran `nixpkgs-review wip`
+- [ ] No packages break due to update
+- [ ] Reviewed upstream changelog
+- [ ] Updated hash correctly
+- [ ] Updated vendorHash/cargoHash if needed
+- [ ] Commit message follows convention
+- [ ] Signed commit (`-s` flag)
+- [ ] For major updates: documented breaking changes
+- [ ] For security updates: referenced CVE
+
+## Create Pull Request
+
+```bash
+# Push branch
+git push -u origin update/package-name
+
+# Create PR
+gh pr create
+
+# Title: package-name: 1.0.0 -> 1.1.0
+# For security: add [security] label
+```
+
+### PR Description Template
+
+```markdown
+## Update Details
+- Old version: 1.0.0
+- New version: 1.1.0
+- [Upstream changelog](https://github.com/owner/repo/releases/tag/v1.1.0)
+
+## Testing
+- [x] Builds successfully
+- [x] Binary executes
+- [x] `--version` shows 1.1.0
+- [x] Ran nixpkgs-review (no breakages)
+
+## Notable Changes
+- Bug fixes and performance improvements
+- No breaking changes
+```
+
+## Batch Updates
+
+For updating multiple related packages:
+
+```bash
+# Update all python packages (example)
+for pkg in package1 package2 package3; do
+  nix-update python3Packages.$pkg --build
+done
+
+# Review all changes together
+nixpkgs-review wip
+
+# Commit message
+git commit -s -m "python3Packages: update multiple packages
+
+- package1: 1.0 -> 1.1
+- package2: 2.0 -> 2.1
+- package3: 3.0 -> 3.2
+"
+```
+
+## Resources
+
+- [nix-update](https://github.com/Mic92/nix-update)
+- [nixpkgs-review](https://github.com/Mic92/nixpkgs-review)
+- [Contributing to Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md)
+- [Package Updates](https://nixos.org/manual/nixpkgs/stable/#sec-package-updates)