SITER-Solar/CONTRIBUTING.md

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:

   git clone <repository-url>
   cd SITER-Solar
   

2. Build the test environment:

   docker build -f Dockerfile.test -t siter-solar-test .
   

3. Run tests:

   docker run --rm siter-solar-test
   

4. Run the analysis script:

   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:

<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

# 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 file for details.

Questions?

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

Thank you for contributing!