nixpkgs/docs/CONTRIBUTING.md

# Contributing

Contributing to m3ta-nixpkgs.

## Setting Up Development Environment

```bash
# 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:

```bash
# 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:

```bash
# 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:

```nix
{
  lib,
  stdenv,
  fetchFromGitHub,
}:
```

### Meta Fields

Always include all fields in package definitions:

```nix
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:

```nix
{ 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](./guides/adding-packages.md) for detailed instructions.

**Note**: Package versions are automatically updated weekly via Gitea Actions using `nix-update`. You don't need to worry about keeping versions current - the automation will create PRs for updates. Just focus on ensuring the package builds and works correctly.

### Package Testing

```bash
# 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)

```nix
# 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`

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

## Development Workflow

### Making Changes

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Flake Validation

```bash
# 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

### Handling Automated Update PRs

The repository has automated package updates via Gitea Actions (see main README for details). When reviewing automated update PRs:

1. **Build and test**: Verify the updated package builds successfully
2. **Check changelinks**: Review upstream release notes for breaking changes
3. **Test functionality**: Ensure the package still works as expected
4. **Review package definition**: Check if any manual adjustments are needed

For urgent updates, you can manually trigger the workflow from the Gitea UI or update the package manually.

### 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:

```nix
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

```bash
# 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](./ARCHITECTURE.md) for design decisions
- Review [Code Patterns](./reference/patterns.md) 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

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