0bbd0fb484
Security: - Remove -k/--api-key CLI option (prevents process list exposure) - API key now only accepted via NREL_API_KEY environment variable Features: - Add API timeout (30s) and retry logic with exponential backoff - Add rate limit detection and graceful test skipping Documentation: - Add AGPLv3 LICENSE file - Add CONTRIBUTING.md with development guidelines - Add CHANGELOG.md following Keep a Changelog format - Add copyright headers to all source files Tests: - Expand test suite from 19 to 52 tests - Add edge case tests (negative values, boundaries) - Add input validation tests - Add financial calculation verification tests - Add rate limit handling to skip tests gracefully - Remove skip-on-failure logic - tests now properly fail All 52 tests pass (19 skipped when API rate limited). 🤖 Generated with [Crush](https://crush.cli.software) Assisted-by: GLM-5 via Crush <crush@charm.land>
185 lines
4.3 KiB
Markdown
185 lines
4.3 KiB
Markdown
# 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!
|