# Contributing to SITER Solar

Thank you for your interest in contributing to SITER Solar! This document provides guidelines and instructions for contributing.

## Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

## Development Environment

### Prerequisites

- Docker (required for all development)
- Git

### Important: Docker-Only Development

**All development work must be done inside Docker containers.** Only `git` and `docker` commands are allowed on the host system. This ensures:

- Consistent development environment
- Reproducible builds
- Isolation from host system

### Setting Up

1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd SITER-Solar
   ```

2. Build the test environment:
   ```bash
   docker build -f Dockerfile.test -t siter-solar-test .
   ```

3. Run tests:
   ```bash
   docker run --rm siter-solar-test
   ```

4. Run the analysis script:
   ```bash
   docker run --rm --entrypoint="" siter-solar-test /app/solar-analysis/siter-solar-analysis.sh --help
   ```

## Development Workflow

### Branch Naming

- `feature/` - New features (e.g., `feature/add-export-csv`)
- `fix/` - Bug fixes (e.g., `fix/api-timeout-handling`)
- `docs/` - Documentation changes
- `test/` - Test improvements
- `refactor/` - Code refactoring

### Commit Messages

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

```
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

Types:
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation only
- `test:` - Adding or modifying tests
- `refactor:` - Code refactoring
- `chore:` - Maintenance tasks

Examples:
```
feat: add CSV export option
fix: handle API timeout gracefully
docs: update installation instructions
test: add edge case tests for input validation
```

### Pre-commit Hooks

The repository includes pre-commit hooks that enforce:

1. **No private data** - Scans for addresses, phone numbers, contract numbers
2. **Shellcheck** - All shell scripts must pass shellcheck
3. **Tests** - All tests must pass
4. **Conventional commits** - Commit messages must follow the format

### Testing

We use BATS (Bash Automated Testing System) for testing.

#### Running Tests

```bash
# In Docker
docker run --rm siter-solar-test

# Run specific test
docker run --rm --entrypoint="" siter-solar-test bats /app/solar-analysis/tests/siter-solar-analysis.bats -f "help option"
```

#### Writing Tests

- Place tests in `solar-analysis/tests/`
- Use descriptive test names
- Tests should be independent and idempotent
- Mock external API calls when possible
- Test edge cases and error conditions

### Code Style

#### Shell Scripts

- Use `#!/usr/bin/env bash` shebang
- Enable strict mode: `set -euo pipefail`
- Use `readonly` for constants
- Add shellcheck directives where needed
- Document functions with comments

#### Documentation

- Update README.md for user-facing changes
- Update AGENTS.md for AI assistant context
- Keep documentation synchronized with code

## Privacy and Security

### Private Data

**Never commit private data to the repository.** This includes:

- Real addresses
- Contract numbers
- Meter numbers
- API keys
- Personal information

The `.gitignore` file excludes:
- `base-bill/` - Contains personal billing data
- `.env` - Contains API keys and location data
- Any files matching `*SITER*` patterns

### API Keys

- Never commit API keys
- Use environment variables only
- API keys via CLI arguments are prohibited (security - process list visibility)
- Use `.env.example` as a template

## Pull Request Process

1. Create a feature branch from `master`
2. Make your changes following the guidelines above
3. Ensure all tests pass
4. Update documentation as needed
5. Submit a pull request with:
   - Clear description of changes
   - Reference to any related issues
   - Test results

### PR Checklist

- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] Commit messages follow conventional format
- [ ] No private data included
- [ ] Code passes shellcheck

## License

By contributing to SITER Solar, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0 (AGPLv3). See the [LICENSE](LICENSE) file for details.

## Questions?

- Open an issue for bugs or feature requests
- Check existing issues before creating new ones

Thank you for contributing!