# Contributing to Aurora Smart Home

Thank you for your interest in contributing to Aurora Smart Home! This document provides guidelines for contributing to this Claude Code skill pack.

## Ways to Contribute

- **Report bugs** - Found something that doesn't work? Open an issue
- **Suggest features** - Have an idea? We'd love to hear it
- **Improve documentation** - Fix typos, clarify explanations, add examples
- **Add templates** - Create new ESPHome or Home Assistant templates
- **Expand references** - Add documentation for sensors, integrations, patterns

## Getting Started

### 1. Fork and Clone

```bash
# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/aurora-smart-home.git
cd aurora-smart-home
```

### 2. Create a Branch

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```

### 3. Make Your Changes

See the style guides below for formatting requirements.

### 4. Test Your Changes

- For ESPHome templates: Run `python scripts/validate_esphome.py your-file.yaml`
- For YAML files: Ensure they parse correctly
- For Markdown: Check that links work and formatting renders properly

### 5. Commit Your Changes

We use [Conventional Commits](https://www.conventionalcommits.org/):

```bash
git commit -m "feat: add new soil moisture sensor template"
git commit -m "fix: correct GPIO pin mapping for ESP32-S3"
git commit -m "docs: expand I2C troubleshooting section"
```

**Commit types:**
- `feat:` - New feature or template
- `fix:` - Bug fix
- `docs:` - Documentation only
- `refactor:` - Code restructuring
- `chore:` - Maintenance tasks

### 6. Push and Create PR

```bash
git push origin feature/your-feature-name
```

Then open a Pull Request on GitHub.

## Style Guides

### Markdown Files

- Use ATX-style headers (`#`, `##`, `###`)
- One sentence per line (for better diffs)
- Use fenced code blocks with language identifiers
- Include examples where possible

### YAML Templates (ESPHome/Home Assistant)

- Include attribution header:
  ```yaml
  # Generated by aurora@aurora-smart-home (esphome skill)
  # https://github.com/tonylofgren/aurora-smart-home
  ```
- Use `!secret` for all credentials
- Add comments explaining non-obvious configurations
- Follow the existing template structure

### Python Scripts

- Follow PEP 8 style guide
- Include docstrings for functions
- Add type hints where practical

## Project Structure

```
aurora-smart-home/
├── esphome/              # ESPHome skill
│   ├── SKILL.md          # Skill definition
│   ├── references/       # Documentation
│   └── assets/templates/ # ESPHome templates
├── home-assistant/       # Home Assistant YAML skill
│   ├── SKILL.md
│   ├── references/
│   └── assets/templates/
├── ha-integration-dev/   # Custom integration skill
│   ├── SKILL.md
│   ├── references/
│   └── assets/templates/
├── examples/             # Complete example projects
└── scripts/              # Utility scripts
```

## Adding New Content

### New ESPHome Template

1. Create file in `esphome/assets/templates/`
2. Follow existing template structure
3. Include attribution header
4. Add entry to `esphome/assets/templates/README.md`

### New Reference Documentation

1. Create file in appropriate `references/` directory
2. Add entry to the skill's `SKILL.md` quick reference table
3. Cross-link from related documents

### New Example Project

1. Create directory in `examples/`
2. Include README.md with setup instructions
3. Include all necessary config files
4. Add secrets.yaml.example (never real secrets)

## Code Review Process

1. All PRs require at least one review
2. CI checks must pass (YAML linting, link checking)
3. Changes should be focused and atomic
4. Large changes should be discussed in an issue first

## Questions?

- Open an issue for questions about contributing
- Check existing issues and discussions first
- Be patient - this is a community project

## License

By contributing, you agree that your contributions will be licensed under the MIT License.