# Contributing Guide

Thank you for your interest in contributing to the ADLee dotfiles project! This guide explains how to contribute to our Arch/CachyOS-focused dotfiles repository.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Making Changes](#making-changes)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Submitting Changes](#submitting-changes)
- [Architecture Overview](#architecture-overview)
- [Project Philosophy](#project-philosophy)

---

## Code of Conduct

- Be respectful to all contributors
- Provide constructive feedback
- Ask questions when unclear
- Help others when possible
- Focus on the code, not the person

---

## Getting Started

### Prerequisites

- Arch Linux or CachyOS
- Git
- Bash/Zsh
- Understanding of shell scripting

### Fork and Clone

```bash
# Fork on GitHub (click Fork button)

# Clone your fork
git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/.dotfiles-dev
cd ~/.dotfiles-dev

# Add upstream for syncing
git remote add upstream https://github.com/adlee-was-taken/dotfiles.git

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

---

## Development Setup

### Install in Development Mode

```bash
cd ~/.dotfiles-dev

# Create a test installation in a temporary directory
export DOTFILES_HOME=/tmp/test-dotfiles
mkdir -p $DOTFILES_HOME

# Link your dev dotfiles
ln -s $(pwd) $DOTFILES_HOME/.dotfiles

# Run installer in test mode
DOTFILES_HOME=$DOTFILES_HOME ./install.sh --skip-deps
```

### Testing Without Overwriting

```bash
# Use Docker or chroot to test in isolated environment
docker run -it archlinux:latest bash
# Inside container:
git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
```

### Validate Changes

```bash
./install.sh --help              # Verify script runs
./install.sh --skip-deps         # Test without dependencies
dotfiles-doctor.sh               # Health check
```

---

## Making Changes

### What to Change

**Good areas for contribution:**
- Bug fixes
- Feature additions for Arch/CachyOS
- Zsh enhancements
- Vim/Neovim configuration improvements
- LastPass integration improvements
- Documentation and guides
- Performance improvements
- Error messages and validation

**Areas to avoid:**
- Adding support for other OS (macOS, Ubuntu, etc.)
- Adding other password managers (1Password, Bitwarden, etc.)
- Adding other editors (Emacs, VS Code, etc.)
- Changes that increase complexity

### Code Organization

```
dotfiles/
├── install.sh              # Main installer - modify carefully
├── dotfiles.conf           # Configuration - add new features here
├── zsh/
│   ├── .zshrc              # Core zsh config
│   ├── aliases.zsh         # Custom aliases
│   ├── themes/             # Prompt themes
│   └── functions/          # Zsh functions (new features go here)
├── vim/                    # Vim configuration
├── nvim/                   # Neovim configuration
├── tmux/                   # Tmux configuration
├── git/                    # Git configuration
├── bin/                    # Shell scripts (utilities and tools)
└── docs/                   # Documentation
```

### Adding a New Feature

**Example: Add a new command palette action**

1. Create function in `zsh/functions/command-palette.zsh`:

```bash
# Add to _command_palette_entries()
case "$entry" in
  "myfeature")
    my-command
    ;;
esac
```

2. Add configuration to `dotfiles.conf`:

```bash
ENABLE_MYFEATURE="ask"
```

3. Add logic to `install.sh`:

```bash
if [[ "$ENABLE_MYFEATURE" == "true" ]]; then
  pacman -S myfeature-package
fi
```

4. Document in `docs/SETUP_GUIDE.md`:

```markdown
### My Feature

Description of feature...
```

5. Test thoroughly before submitting PR.

---

## Coding Standards

### Shell Script Style

```bash
# Good practices
#!/bin/bash
set -euo pipefail

# Use descriptive variable names
local readonly config_file="$HOME/.dotfiles/dotfiles.conf"

# Quote all variables
echo "$variable"

# Use functions with local variables
function my_function() {
  local readonly required_arg="$1"
  local optional_arg="${2:-default}"
  
  # Error handling
  if [[ ! -f "$required_arg" ]]; then
    echo "Error: File not found: $required_arg" >&2
    return 1
  fi
  
  # Return explicitly
  return 0
}

# Use [[ ]] instead of [ ]
if [[ "$condition" == "true" ]]; then
  echo "Good"
fi

# Comment complex logic
# Check if file exists and is readable
if [[ -r "$config_file" ]]; then
  source "$config_file"
fi
```

### Zsh Style

```zsh
# Functions in zsh/functions/
function my-feature() {
  local -a args=("$@")
  
  # Parse arguments
  case "${args[1]}" in
    list)
      # Implementation
      ;;
    *)
      echo "Usage: my-feature {list|create|delete}"
      return 1
      ;;
  esac
}

# Aliases in zsh/aliases.zsh
alias mf='my-feature'

# Set shell options
setopt nocaseglob
setopt noshglob

# Use proper quoting
print -P "%F{blue}%Btext%b%f"
```

### Comments and Documentation

```bash
# Comment Why, not What
# BAD: Add 5 to count
count=$((count + 5))

# GOOD: Increment by hardcoded snapshot count limit per policy
count=$((count + 5))

# Use TODO for future work
# TODO: Add support for encrypted backups

# Document functions
# my_function: Create a backup of the dotfiles
# Arguments:
#   $1: Backup name
# Returns:
#   0 on success, 1 on error
function my_function() {
  # ...
}
```

### Error Handling

```bash
# Always check critical operations
if ! pacman -S package; then
  echo "Error: Failed to install package" >&2
  return 1
fi

# Use set -e with care (only for critical scripts)
set -euo pipefail

# Provide helpful error messages
if [[ ! -d "$DOTFILES_HOME" ]]; then
  echo "Error: Dotfiles not found at $DOTFILES_HOME" >&2
  echo "Please run: git clone <repo> $DOTFILES_HOME" >&2
  return 1
fi
```

---

## Testing

### Manual Testing

```bash
# Test installer
./install.sh --help
./install.sh --skip-deps
dfd          # Run health check

# Test new features
./zsh/functions/my-feature.zsh test
```

### Validation Checklist

- [ ] No errors in `shellcheck` (if available)
- [ ] Script runs without errors
- [ ] `dotfiles-doctor.sh` passes
- [ ] Feature works as documented
- [ ] No breaking changes for existing users
- [ ] Works on both Arch and CachyOS
- [ ] Tested with both bash and zsh

```bash
# Run shellcheck on modified scripts
shellcheck install.sh bin/*.sh zsh/functions/*.zsh
```

### Testing Across Arch/CachyOS

```bash
# Test on Arch Linux
# Test on CachyOS (if available)
# Test on fresh installation
# Test on system with existing dotfiles

# Verify:
# - Installation completes
# - All features work
# - No data loss
# - Can uninstall cleanly
```

---

## Submitting Changes

### Commit Messages

```bash
# Good commit message format
# First line: Brief summary (50 chars max)
# Blank line
# Detailed explanation (if needed)

git commit -m "Add fuzzy search to password manager

- Implement fzf integration for pw command
- Add pwf alias for quick password copy
- Update documentation with examples
- Tested on Arch and CachyOS"
```

### Commit Guidelines

- One logical change per commit
- Commit frequently
- Include related changes together
- Meaningful commit messages

### Before Submitting PR

```bash
# Sync with upstream
git fetch upstream
git rebase upstream/main

# Clean up commits
# (squash, reorder, reword as needed)

# Final validation
./install.sh --help
./install.sh --skip-deps
dotfiles-doctor.sh
```

### Pull Request Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Performance improvement

## Related Issues
Fixes #123

## Testing
- [ ] Tested on Arch Linux
- [ ] Tested on CachyOS
- [ ] All features work
- [ ] No regressions

## Checklist
- [ ] Code follows style guide
- [ ] Documentation updated
- [ ] Changes are tested
- [ ] No breaking changes
- [ ] Commits are clean
```

### PR Review Process

1. CI/automated checks pass
2. Code review (expect feedback)
3. Revisions made if needed
4. Final approval
5. Merge to main

---

## Architecture Overview

### Installation Flow

```
install.sh
├── Check OS (Arch/CachyOS only)
├── Load dotfiles.conf
├── Check dependencies
├── Install system packages
├── Create symlinks
├── Configure zsh
├── Initialize git config
└── Run post-install setup
```

### Module Structure

Each feature is mostly self-contained:

```
Feature: Password Manager
├── zsh/functions/password-manager.zsh    # Core functions
├── bin/dotfiles-vault.sh                 # Supporting script
├── dotfiles.conf entries                 # Configuration
├── install.sh logic                      # Installation
└── docs/SETUP_GUIDE.md section           # Documentation
```

### Configuration Hierarchy

```
install.sh (defaults)
  ↓
dotfiles.conf (user config)
  ↓
~/.zshrc (shell execution)
  ↓
~/.zshrc.local (machine-specific)
```

---

## Project Philosophy

### Design Principles

1. **Arch/CachyOS First** - Optimize for Arch/CachyOS, not other systems
2. **Simplicity** - Reduce complexity over time
3. **Single Tools** - One password manager, one editor, one shell
4. **User Customization** - Easy to customize without modification
5. **Documentation** - Features need good documentation
6. **Backward Compatibility** - Breaking changes discussed first

### What We Value

- ✅ Productivity
- ✅ Clarity
- ✅ Reliability
- ✅ Minimalism (not bloat)
- ✅ User autonomy

### What We Don't Value

- ❌ Supporting many OSes
- ❌ Supporting many tools
- ❌ Complex configuration
- ❌ Undocumented features
- ❌ Breaking user workflows

---

## Getting Help

### Questions

- Check [README.md](../README.md)
- Check [SETUP_GUIDE.md](SETUP_GUIDE.md)
- Check existing GitHub issues
- Ask in a new GitHub issue

### Feature Requests

1. Check if already requested (GitHub issues)
2. Describe use case clearly
3. Explain why it fits project scope
4. Include examples

### Bug Reports

1. Run `dotfiles-doctor.sh`
2. Include error output
3. Include OS and CachyOS/Arch version
4. Include steps to reproduce
5. Include expected vs actual behavior

---

## Recognition

Contributors are recognized in:
- GitHub Contributors page
- [CONTRIBUTORS.md](CONTRIBUTORS.md) file
- Release notes for significant changes

Thank you for contributing! 🙏

---

For more information:
- [README.md](../README.md)
- [SETUP_GUIDE.md](SETUP_GUIDE.md)
- [GitHub Issues](https://github.com/adlee-was-taken/dotfiles/issues)