Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
190 lines (133 loc) · 3.54 KB

CONTRIBUTING.md

File metadata and controls

190 lines (133 loc) · 3.54 KB

Contributing

Guidelines for contributing to this NixOS dotfiles repository.

Repository Structure

See docs/ARCHITECTURE.md for a detailed overview of the codebase structure.

Development Setup

# Clone the repository
git clone git@github.com:robcohen/dotfiles.git
cd dotfiles

# Enter development shell (provides formatting tools, etc.)
nix develop

# Or use direnv
direnv allow

Code Style

Nix Formatting

All Nix files are formatted with nixfmt. Run before committing:

nix fmt

Naming Conventions

  • Files: kebab-case.nix (e.g., bluetooth-common.nix)
  • Options: camelCase (e.g., enablePermissions)
  • Modules: Descriptive names matching functionality

Module Structure

New modules should follow this template:

# modules/category/my-module.nix
# Brief description of what this module does
{ config, lib, pkgs, ... }:

let
  cfg = config.category.myModule;
in {
  options.category.myModule = {
    enable = lib.mkEnableOption "description of module";

    someOption = lib.mkOption {
      type = lib.types.str;
      default = "value";
      description = "What this option does";
    };
  };

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

Function Arguments

Standardize on this order:

{ config, lib, pkgs, inputs, ... }:

Making Changes

Adding a New Program Configuration

  1. Create profiles/programs/myprogram.nix
  2. Import it in profiles/user.nix
  3. Optionally add feature gating: 
    lib.mkIf (hasFeature "development") { ... }

Adding a New Hardware Module

  1. Create modules/hardware/mydevice.nix with options
  2. Import in relevant host configurations
  3. Document options in the file

Modifying Host Configurations

  1. Prefer extracting common code to modules
  2. Use lib.mkIf for conditional configuration
  3. Add comments explaining non-obvious settings

Pre-Commit Checks

This repository uses pre-commit hooks for:

  • detect-secrets: Prevents accidental secret commits
  • gitleaks: Scans for hardcoded credentials
  • nixfmt-check: Ensures Nix formatting

Install hooks:

pre-commit install

Run manually:

pre-commit run --all-files

Testing Changes

Build Without Switching

# Test NixOS build
nixos-rebuild build --flake .#hostname

# Test Home Manager build
home-manager build --flake .#user@hostname

Check Flake

# Show all outputs
nix flake show

# Check for errors
nix flake check

Dry Run

# See what would change
nixos-rebuild dry-activate --flake .#hostname

Commit Messages

Follow conventional commits:

type(scope): description

[optional body]

Types:

  • feat: New feature
  • fix: Bug fix
  • refactor: Code restructuring
  • docs: Documentation
  • chore: Maintenance

Examples:

feat(bluetooth): add common Bluetooth module
fix(snix): correct resume device UUID
refactor(hosts): extract system tuning to module
docs: add ARCHITECTURE.md

Pull Request Process

  1. Create a feature branch
  2. Make changes following the style guide
  3. Run nix fmt and pre-commit run --all-files
  4. Test build on at least one host
  5. Submit PR with clear description

Security

  • Never commit secrets - Use SOPS for sensitive data
  • Review security implications - Especially for kernel params, firewall rules
  • Document security trade-offs - If disabling security features, explain why

Getting Help

  • Check existing code for patterns
  • Review docs/ for guides
  • Open an issue for questions