Commit 313020e628a7

@@ -0,0 +1,524 @@
+# Nixpkgs Workflow
+
+Work with the NixOS/nixpkgs repository: review PRs, update packages, and contribute.
+
+## When to Use
+
+- "review nixpkgs pr"
+- "update nixpkgs package"
+- "nixpkgs contribution"
+- "nixpkgs-review"
+
+## Quick Commands
+
+### Review PR
+```bash
+# Review pull request
+nixpkgs-review pr 12345
+
+# Review and post results
+nixpkgs-review pr 12345 --post-result
+
+# Review specific packages only
+nixpkgs-review pr 12345 -p firefox
+```
+
+### Update Package
+```bash
+# Update package version
+nix-update package-name
+
+# Update and build
+nix-update --build package-name
+
+# Update, build, and commit
+nix-update --build --commit package-name
+```
+
+### Review Local Changes
+```bash
+# Review uncommitted changes
+nixpkgs-review wip
+
+# Review staged changes only
+nixpkgs-review wip --staged
+
+# Review specific commit
+nixpkgs-review rev HEAD
+```
+
+## nixpkgs-review
+
+### Installation
+```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
+```
+
+### Basic PR Review
+```bash
+# Review PR by number
+nixpkgs-review pr 12345
+
+# Review PR by URL
+nixpkgs-review pr https://github.com/NixOS/nixpkgs/pull/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
+```
+
+### Post Results to PR
+```bash
+# Post build report as comment
+nixpkgs-review pr 12345 --post-result
+
+# Requires GitHub authentication
+# Set up with gh, hub, or GITHUB_TOKEN
+```
+
+### GitHub Authentication
+```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 Options
+```bash
+# Build only specific packages
+nixpkgs-review pr 12345 -p firefox chromium
+
+# Build packages matching regex
+nixpkgs-review pr 12345 --package-regex "python.*"
+
+# Review for multiple systems
+nixpkgs-review pr 12345 --system x86_64-linux,aarch64-linux
+
+# Don't enter shell (non-interactive)
+nixpkgs-review pr 12345 --no-shell
+
+# Run custom command instead of shell
+nixpkgs-review pr 12345 --run "nix-shell -p hello --run hello"
+
+# Print results to stdout
+nixpkgs-review pr 12345 --print-result
+
+# Sandbox mode (protect HOME)
+nixpkgs-review pr 12345 --sandbox
+```
+
+### Interactive Commands
+```bash
+# After nixpkgs-review pr drops you in shell:
+
+# Approve PR (adds approval comment)
+nix-shell> nixpkgs-review approve
+
+# Merge PR (requires maintainer access)
+nix-shell> nixpkgs-review merge
+
+# Show PR comments
+nix-shell> nixpkgs-review comments
+
+# Exit shell
+nix-shell> exit
+```
+
+### Review Local Changes
+```bash
+# Review your uncommitted changes
+nixpkgs-review wip
+
+# Review staged changes only
+nixpkgs-review wip --staged
+
+# Review specific commit
+nixpkgs-review rev HEAD
+
+# Review commit range
+nixpkgs-review rev HEAD~3..HEAD
+
+# Review remote branch
+nixpkgs-review rev origin/staging
+```
+
+## nix-update
+
+### Installation
+```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 Package Update
+```bash
+# Update package to latest version
+nix-update package-name
+
+# Update will:
+# 1. Fetch latest version from upstream
+# 2. Update version in package expression
+# 3. Update source hash
+# 4. Update cargo/npm hashes if applicable
+```
+
+### Update Options
+```bash
+# Update and build
+nix-update --build package-name
+
+# Update and run tests
+nix-update --test package-name
+
+# Update and enter nix-shell
+nix-update --shell package-name
+
+# Update and review with nixpkgs-review
+nix-update --review package-name
+
+# Update and format file
+nix-update --format package-name
+
+# Update and commit
+nix-update --commit package-name
+
+# Combine options
+nix-update --build --test --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 Source Types
+```bash
+# PyPI package
+nix-update python-package
+
+# GitHub release
+nix-update github-package
+
+# Git repository
+nix-update --version=branch=main git-package
+
+# Cargo.lock update
+nix-update --build rust-package
+```
+
+## Contributing to nixpkgs
+
+### Setup nixpkgs Repository
+```bash
+# Clone nixpkgs
+cd ~/src/github.com/NixOS
+git clone https://github.com/NixOS/nixpkgs.git
+cd nixpkgs
+
+# Add upstream remote
+git remote add upstream https://github.com/NixOS/nixpkgs.git
+
+# Create development environment
+nix-shell -p nix-update nixpkgs-review nixfmt-rfc-style
+```
+
+### Update Package Workflow
+```bash
+# 1. Create branch
+git checkout -b update/package-name
+
+# 2. Update package
+nix-update --build --commit package-name
+
+# 3. Review changes
+nixpkgs-review wip
+
+# 4. Push and create PR
+git push -u origin update/package-name
+gh pr create
+```
+
+### Add New Package Workflow
+```bash
+# 1. Create branch
+git checkout -b pkg/new-package
+
+# 2. Create package file
+mkdir -p pkgs/by-name/ne/new-package
+vim pkgs/by-name/ne/new-package/package.nix
+
+# 3. Test build
+nix-build -A new-package
+
+# 4. Review
+nixpkgs-review wip
+
+# 5. Format
+nixfmt pkgs/by-name/ne/new-package/package.nix
+
+# 6. Commit and push
+git add .
+git commit -s -m "new-package: init at 1.0.0"
+git push -u origin pkg/new-package
+gh pr create
+```
+
+### Fix Package Workflow
+```bash
+# 1. Create branch
+git checkout -b fix/package-name-issue
+
+# 2. Make changes
+vim pkgs/path/to/package/default.nix
+
+# 3. Test build
+nix-build -A package-name
+
+# 4. Review all affected packages
+nixpkgs-review wip
+
+# 5. Commit and push
+git add .
+git commit -s -m "package-name: fix issue description"
+git push -u origin fix/package-name-issue
+gh pr create
+```
+
+## nixpkgs-review Best Practices
+
+### Review Workflow
+```bash
+# 1. Review PR
+nixpkgs-review pr 12345
+
+# 2. In the nix-shell, test packages
+nix-shell> package-name --version
+nix-shell> package-name --help
+
+# 3. Check for issues
+nix-shell> ls -la $(which package-name)
+
+# 4. If good, approve
+nix-shell> nixpkgs-review approve
+
+# 5. Exit
+nix-shell> exit
+```
+
+### What to Check
+1. **Package builds successfully**: No build errors
+2. **Tests pass**: If package has tests
+3. **Binary works**: Can execute and shows help
+4. **Dependencies correct**: No missing runtime dependencies
+5. **License correct**: Matches upstream
+6. **Meta attributes**: Description, homepage accurate
+7. **No regressions**: Dependent packages still build
+
+### Common Review Scenarios
+
+#### Version Update PR
+```bash
+# Review version bump
+nixpkgs-review pr 12345
+
+# Check:
+# - Version number correct
+# - Hash updated correctly
+# - Tests still pass
+# - No breaking changes
+```
+
+#### New Package PR
+```bash
+# Review new package
+nixpkgs-review pr 12345 -p new-package
+
+# Check:
+# - Package name follows conventions
+# - In correct category
+# - Meta attributes complete
+# - License specified
+# - Maintainers added
+# - Tests included
+```
+
+#### Security Update PR
+```bash
+# Review security update
+nixpkgs-review pr 12345
+
+# Check:
+# - CVE mentioned in description
+# - Version fixes vulnerability
+# - All variants updated (if multiple)
+# - Consider backport to stable
+```
+
+## Working with Package Sets
+
+### Python Packages
+```bash
+# Update Python package
+nix-update python3Packages.package-name
+
+# Review Python package PR
+nixpkgs-review pr 12345 -p python3Packages.package-name
+```
+
+### Haskell Packages
+```bash
+# Update Haskell package
+nix-update haskellPackages.package-name
+
+# Update all Haskell packages
+# (This is done by nixpkgs maintainers)
+```
+
+### Node Packages
+```bash
+# Node packages use node2nix
+# Manual update required
+
+# Review node package
+nixpkgs-review pr 12345 -p nodePackages.package-name
+```
+
+## Advanced nixpkgs-review
+
+### Remote Builders
+```bash
+# Use remote builder
+nixpkgs-review pr 12345 \
+  --remote user@builder-host \
+  --remote-build-host user@builder-host
+
+# Configure in ~/.config/nixpkgs-review/config.toml
+[remote]
+host = "user@builder-host"
+```
+
+### Custom Build Options
+```bash
+# Use specific nixpkgs checkout
+nixpkgs-review pr 12345 --nixpkgs /path/to/nixpkgs
+
+# Extra nix options
+nixpkgs-review pr 12345 --extra-nixpkgs-config '{ allowUnfree = true; }'
+```
+
+### Batch Review
+```bash
+# Review multiple PRs
+for pr in 12345 12346 12347; do
+  nixpkgs-review pr $pr --no-shell --post-result
+done
+```
+
+## Troubleshooting
+
+### Build Failures
+```bash
+# Keep build directory on failure
+nixpkgs-review pr 12345 --keep-going
+
+# Show full build logs
+nixpkgs-review pr 12345 | tee review.log
+```
+
+### Authentication Issues
+```bash
+# Check GitHub token
+gh auth status
+
+# Refresh token
+gh auth refresh
+
+# Set token manually
+export GITHUB_TOKEN=$(gh auth token)
+```
+
+### Evaluation Errors
+```bash
+# Show evaluation trace
+nixpkgs-review pr 12345 --show-trace
+
+# Check for syntax errors
+nix-instantiate --parse default.nix
+```
+
+## Resources
+
+- [nixpkgs-review](https://github.com/Mic92/nixpkgs-review)
+- [nix-update](https://github.com/Mic92/nix-update)
+- [nixpkgs Contributing Guide](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md)
+- [Reviewing Contributions](https://ryantm.github.io/nixpkgs/contributing/reviewing-contributions/)
+- [Nixpkgs Manual](https://nixos.org/manual/nixpkgs/stable/)
+
+## Commit Message Format
+
+### Version Updates
+```
+package-name: 1.0.0 -> 1.1.0
+```
+
+### New Packages
+```
+package-name: init at 1.0.0
+```
+
+### Fixes
+```
+package-name: fix build on aarch64-linux
+```
+
+### Multi-Package Updates
+```
+pythonPackages: update multiple packages
+
+- package1: 1.0 -> 1.1
+- package2: 2.0 -> 2.1
+```
+
+## Tips and Tricks
+
+1. **Use --post-result**: Auto-comment on PRs to help maintainers
+2. **Review regularly**: Help reduce PR backlog
+3. **Test on your system**: Real-world testing is valuable
+4. **Be thorough but kind**: Constructive feedback
+5. **Check ofborg results**: CI results before reviewing
+6. **Use nix-update**: Automate version updates
+7. **Review related PRs**: Check for conflicts
+8. **Comment on approach**: Not just build success
+9. **Approve quickly**: Don't block good PRs
+10. **Learn from reviews**: Read other reviewers' comments

@@ -8,12 +8,18 @@ description: Expert guidance on Nix, NixOS, and home-manager best practices. USE
 ## Purpose
 Expert guidance on Nix, NixOS, and home-manager following best practices.
 
+## Context Detection
+
+### nixpkgs Repository
+When working in the NixOS/nixpkgs repository (detected by git remote or path like `~/src/github.com/NixOS/nixpkgs`), prefer the Nixpkgs workflow for PR reviews, package updates, and contributions.
+
 ## Workflow Routing
 
 When the user's request matches specific Nix operations, route to the appropriate workflow:
 
 | Workflow | Trigger | File |
 |----------|---------|------|
+| **Nixpkgs** | "review PR", "nixpkgs-review", "nix-update", "contribute to nixpkgs" | `workflows/Nixpkgs.md` |
 | **Build** | "build nix package", "nixos-rebuild build", "compile nix" | `workflows/Build.md` |
 | **Debug** | "debug nix", "nix error", "troubleshoot build", "evaluation error" | `workflows/Debug.md` |
 | **Develop** | "development shell", "nix develop", "devShell", "direnv" | `workflows/Develop.md` |