nixos-dotfiles/CONTRIBUTING.md

Contributing to NixOS Dotfiles

First off, thanks for taking the time to contribute! 🎉

For New Users

If you're new to this repository:

1. Read the documentation

   • Quick Start Guide
   • Architecture Overview
   • Module Guide

2. Understand the structure

   • hosts/ - Host-specific configurations
   • modules/nixos/ - System-level modules
   • modules/home-manager/ - User-level modules
   • config/ - Application dotfiles

Making Changes

For Your Own Fork

1. Clone and customize

   git clone https://github.com/YOUR_USERNAME/nixos-dotfiles ~/nixos-dotfiles
   cd ~/nixos-dotfiles
   

2. Update personal information

   • Change username in hosts/nixos-btw/home.nix and modules/nixos/core.nix
   • Update Git info in modules/home-manager/git.nix
   • Copy your hardware config: sudo cp /etc/nixos/hardware-configuration.nix hosts/nixos-btw/

3. Test your changes

   make build  # Test build without applying
   make test   # Test without making it permanent
   make switch # Apply permanently
   

For Contributing Back

1. Fork the repository

2. Create a feature branch

   git checkout -b feature/my-awesome-feature
   

3. Make your changes

   • Follow the existing code style
   • Add comments for complex configurations
   • Update documentation if needed

4. Test thoroughly

   make check  # Validate flake
   make build  # Test build
   

5. Commit with clear messages

   git commit -m "Add: Feature description"
   

   Use prefixes:

   • Add: - New feature
   • Fix: - Bug fix
   • Update: - Update existing feature
   • Docs: - Documentation changes
   • Refactor: - Code restructuring

6. Push and create Pull Request

   git push origin feature/my-awesome-feature
   

Code Style

Nix Files

• Use 2 spaces for indentation
• Add comments for non-obvious configurations
• Group related settings together
• Keep modules focused on single responsibilities

Example:

{ pkgs, ... }:

{
  # Audio configuration
  services.pipewire = {
    enable = true;
    pulse.enable = true;  # PulseAudio compatibility
  };
}

Comments

• Explain why, not what (the code shows what)
• Add comments for hardware-specific tweaks
• Document any workarounds or hacks

Module Guidelines

Creating New Modules

1. Keep it focused - One module = One domain
2. Make it reusable - Avoid hardcoding user-specific values
3. Document it - Add comments and update MODULE_GUIDE.md
4. Test it - Ensure it builds and works

Module Template

# modules/nixos/my-feature.nix
{ config, pkgs, ... }:

{
  # Brief description of what this module does
  
  # Group related configurations
  services.my-service = {
    enable = true;
    # Add inline comments for complex settings
    setting = "value";
  };
}

Submitting Issues

Bug Reports

Include:

• NixOS version (nixos-version)
• Steps to reproduce
• Expected vs actual behavior
• Error messages (if any)

Feature Requests

Include:

• Clear description of the feature
• Use case / motivation
• Examples from other configs (if applicable)

Questions?

• Open an issue for configuration questions
• Check existing issues and PRs first
• Be respectful and patient

License

By contributing, you agree that your contributions will be included under the same terms as the original repository.

---

Thank you for contributing! 🚀