nixpkgs/docs/CONTRIBUTING.md

Contributing

Contributing to m3ta-nixpkgs.

Setting Up Development Environment

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

# Enter development shell (includes linting tools)
nix develop

# Or use a specific shell
nix develop .#python
nix develop .#devops

Code Style and Formatting

Formatting

Use alejandra to format Nix files:

# Format all files
nix fmt

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

Always run nix fmt before committing.

Linting

Linting tools are only available inside the dev shell:

# Enter dev shell first
nix develop

# Run statix (linter)
statix check .

# Run deadnix (find dead code)
deadnix .

Conventions

Naming

• Packages: lowercase-hyphen (e.g., hyprpaper-random)
• Variables: camelCase (e.g., portHelpers)
• Module options: m3ta.* namespace
• Files: lowercase-hyphen (e.g., my-module.nix)

Imports

Multi-line, trailing commas:

{
  lib,
  stdenv,
  fetchFromGitHub,
}:

Meta Fields

Always include all fields in package definitions:

meta = with lib; {
  description = "Short description";
  homepage = "https://github.com/author/repo";
  license = licenses.mit;
  platforms = platforms.linux;
  mainProgram = "program-name";
};

Module Pattern

Standard module pattern:

{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.myModule;
in {
  options.m3ta.myModule = {
    enable = mkEnableOption "description";
  };

  config = mkIf cfg.enable {
    # Configuration
  };
}

Adding a Package

1. Create package directory in pkgs/your-package/
2. Write default.nix with package definition
3. Register in pkgs/default.nix

See Adding Packages Guide for detailed instructions.

Package Testing

# Build the package
nix build .#your-package

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

# Check with linter
nix develop
statix check pkgs/your-package/

Adding a NixOS Module

1. Create module file in modules/nixos/your-module.nix
2. Import in modules/nixos/default.nix (or use directly)

# modules/nixos/default.nix
{
  imports = [
    ./your-module.nix
    ./other-module.nix
  ];
}

Adding a Home Manager Module

1. Choose appropriate category: cli/, coding/, or root
2. Create module file
3. Import in category's default.nix or root default.nix

# modules/home-manager/cli/default.nix
{
  imports = [
    ./your-tool.nix
  ];
}

Development Workflow

Making Changes

# Create feature branch
git checkout -b feature/your-change

# Make changes

# Format code
nix fmt

# Test builds
nix build .#your-package
nix flake check

# Lint
nix develop
statix check .
deadnix .

Commit Format

Use conventional commits:

type: brief description

Types:
- feat:    New feature
- fix:      Bug fix
- docs:     Documentation changes
- style:    Code style changes (formatting)
- refactor: Code refactoring
- chore:    Maintenance tasks
- test:     Adding or updating tests

Examples:

feat: add new package for myapp
fix: resolve port conflict in mem0 module
docs: update installation instructions
style: format nix files
refactor: simplify port management
chore: update dependencies

Before Committing

# Format all files
nix fmt

# Validate flake
nix flake check

# Run linters
nix develop
statix check .
deadnix .

# Add files
git add .

# Commit
git commit -m "type: description"

Testing

Package Testing

# Build for specific system
nix build .#your-package --system x86_64-linux

# Test on different systems
nix build .#your-package --system aarch64-linux

Module Testing

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

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

Flake Validation

# Validate all outputs
nix flake check

# Show all outputs
nix flake show

Pull Requests

Before Submitting

1. Code formatted with nix fmt
2. Passes statix check .
3. Passes deadnix .
4. Passes nix flake check
5. New packages include meta fields
6. Documentation updated if needed
7. Commit messages follow convention

PR Description

Include:

• What changed and why
• How to test
• Any breaking changes
• Related issues

Troubleshooting

Hash Errors

When building packages, you may encounter hash errors:

got: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
expected: sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=

Solution: Copy the got hash and update the package:

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

Dependency Not Found

If a package isn't found, check:

1. Package registered in pkgs/default.nix
2. Overlay applied in your configuration
3. System matches supported platform

Linting Errors

# Fix statix issues manually or use auto-fix where available
statix fix .

# Review deadnix suggestions
deadnix -e .

Getting Help

• Check existing packages and modules for patterns
• Read Architecture for design decisions
• Review Code Patterns for conventions
• Open an issue for questions

Anti-Patterns

Don't	Do Instead
lib.fakeHash in commits	Get real hash: nix build, copy from error
Flat module files	Organize by category (cli/, coding/)
Hardcode ports	Use m3ta.ports module
Skip meta fields	Include all: description, homepage, license, platforms, mainProgram
with pkgs; in modules	Explicit pkgs.package or with pkgs; [ ... ] in lists only
Suppress type errors	Fix underlying type issues
Delete tests to "pass"	Fix failing tests

Code Review Checklist

• Follows naming conventions
• Properly formatted (nix fmt)
• Passes linting (statix, deadnix)
• Has complete meta fields (packages)
• Documentation updated if needed
• No dead code
• No obvious bugs or issues
• Appropriate for scope

Release Process

This is a personal repository, but semantic versioning is followed for tags:

1. Update versions as needed
2. Update changelog
3. Tag release
4. Push tags

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0