mirror of
https://github.com/jpawlowski/hass.tibber_prices.git
synced 2026-03-30 13:23:41 +00:00
dff0faeef5
Changed all documentation links from version-specific tags (v0.20.0) to main branch references. This makes documentation maintenance-free - links stay current as code evolves. Updated 38 files across: - docs/developer/docs/ (7 files) - docs/developer/versioned_docs/version-v0.21.0/ (8 files) - docs/developer/versioned_docs/version-v0.22.0/ (8 files) Impact: Documentation links no longer break when new versions are released. Links always point to current code implementation.
185 lines
7.9 KiB
Markdown
185 lines
7.9 KiB
Markdown
# Developer Documentation
|
|
|
|
This section contains documentation for contributors and maintainers of the **Tibber Prices custom integration**.
|
|
|
|
:::info Community Project
|
|
This is an independent, community-maintained custom integration for Home Assistant. It is **not** an official Tibber product and is **not** affiliated with Tibber AS.
|
|
:::
|
|
|
|
## 📚 Developer Guides
|
|
|
|
- **[Setup](setup.md)** - DevContainer, environment setup, and dependencies
|
|
- **[Architecture](architecture.md)** - Code structure, patterns, and conventions
|
|
- **[Period Calculation Theory](period-calculation-theory.md)** - Mathematical foundations, Flex/Distance interaction, Relaxation strategy
|
|
- **[Timer Architecture](timer-architecture.md)** - Timer system, scheduling, coordination (3 independent timers)
|
|
- **[Caching Strategy](caching-strategy.md)** - Cache layers, invalidation, debugging
|
|
- **[Testing](testing.md)** - How to run tests and write new test cases
|
|
- **[Release Management](release-management.md)** - Release workflow and versioning process
|
|
- **[Coding Guidelines](coding-guidelines.md)** - Style guide, linting, and best practices
|
|
- **[Refactoring Guide](refactoring-guide.md)** - How to plan and execute major refactorings
|
|
|
|
## 🤖 AI Documentation
|
|
|
|
The main AI/Copilot documentation is in [`AGENTS.md`](https://github.com/jpawlowski/hass.tibber_prices/blob/main/AGENTS.md). This file serves as long-term memory for AI assistants and contains:
|
|
|
|
- Detailed architectural patterns
|
|
- Code quality rules and conventions
|
|
- Development workflow guidance
|
|
- Common pitfalls and anti-patterns
|
|
- Project-specific patterns and utilities
|
|
|
|
**Important:** When proposing changes to patterns or conventions, always update [`AGENTS.md`](https://github.com/jpawlowski/hass.tibber_prices/blob/main/AGENTS.md) to keep AI guidance consistent.
|
|
|
|
### AI-Assisted Development
|
|
|
|
This integration is developed with extensive AI assistance (GitHub Copilot, Claude, and other AI tools). The AI handles:
|
|
|
|
- **Pattern Recognition**: Understanding and applying Home Assistant best practices
|
|
- **Code Generation**: Implementing features with proper type hints, error handling, and documentation
|
|
- **Refactoring**: Maintaining consistency across the codebase during structural changes
|
|
- **Translation Management**: Keeping 5 language files synchronized
|
|
- **Documentation**: Generating and maintaining comprehensive documentation
|
|
|
|
**Quality Assurance:**
|
|
|
|
- Automated linting with Ruff (120-char line length, max complexity 25)
|
|
- Home Assistant's type checking and validation
|
|
- Real-world testing in development environment
|
|
- Code review by maintainer before merging
|
|
|
|
**Benefits:**
|
|
|
|
- Rapid feature development while maintaining quality
|
|
- Consistent code patterns across all modules
|
|
- Comprehensive documentation maintained alongside code
|
|
- Quick bug fixes with proper understanding of context
|
|
|
|
**Limitations:**
|
|
|
|
- AI may occasionally miss edge cases or subtle bugs
|
|
- Some complex Home Assistant patterns may need human review
|
|
- Translation quality depends on AI's understanding of target language
|
|
- User feedback is crucial for discovering real-world issues
|
|
|
|
If you're working with AI tools on this project, the [`AGENTS.md`](https://github.com/jpawlowski/hass.tibber_prices/blob/main/AGENTS.md) file provides the context and patterns that ensure consistency.
|
|
|
|
## 🚀 Quick Start for Contributors
|
|
|
|
1. **Fork and clone** the repository
|
|
2. **Open in DevContainer** (VS Code: "Reopen in Container")
|
|
3. **Run setup**: `./scripts/setup/setup` (happens automatically via `postCreateCommand`)
|
|
4. **Start development environment**: `./scripts/develop`
|
|
5. **Make your changes** following the [Coding Guidelines](coding-guidelines.md)
|
|
6. **Run linting**: `./scripts/lint`
|
|
7. **Validate integration**: `./scripts/release/hassfest`
|
|
8. **Test your changes** in the running Home Assistant instance
|
|
9. **Commit using Conventional Commits** format
|
|
10. **Open a Pull Request** with clear description
|
|
|
|
## 🛠️ Development Tools
|
|
|
|
The project includes several helper scripts in `./scripts/`:
|
|
|
|
- `bootstrap` - Initial setup of dependencies
|
|
- `develop` - Start Home Assistant in debug mode (auto-cleans .egg-info)
|
|
- `clean` - Remove build artifacts and caches
|
|
- `lint` - Auto-fix code issues with ruff
|
|
- `lint-check` - Check code without modifications (CI mode)
|
|
- `hassfest` - Validate integration structure (JSON, Python syntax, required files)
|
|
- `setup` - Install development tools (git-cliff, @github/copilot)
|
|
- `prepare-release` - Prepare a new release (bump version, create tag)
|
|
- `generate-release-notes` - Generate release notes from commits
|
|
|
|
## 📦 Project Structure
|
|
|
|
```
|
|
custom_components/tibber_prices/
|
|
├── __init__.py # Integration setup
|
|
├── coordinator.py # Data update coordinator with caching
|
|
├── api.py # Tibber GraphQL API client
|
|
├── price_utils.py # Price enrichment functions
|
|
├── average_utils.py # Average calculation utilities
|
|
├── sensor/ # Sensor platform (package)
|
|
│ ├── __init__.py # Platform setup
|
|
│ ├── core.py # TibberPricesSensor class
|
|
│ ├── definitions.py # Entity descriptions
|
|
│ ├── helpers.py # Pure helper functions
|
|
│ └── attributes.py # Attribute builders
|
|
├── binary_sensor.py # Binary sensor platform
|
|
├── entity_utils/ # Shared entity helpers
|
|
│ ├── icons.py # Icon mapping logic
|
|
│ ├── colors.py # Color mapping logic
|
|
│ └── attributes.py # Common attribute builders
|
|
├── services.py # Custom services
|
|
├── config_flow.py # UI configuration flow
|
|
├── const.py # Constants and helpers
|
|
├── translations/ # Standard HA translations
|
|
└── custom_translations/ # Extended translations (descriptions)
|
|
```
|
|
|
|
## 🔍 Key Concepts
|
|
|
|
**DataUpdateCoordinator Pattern:**
|
|
|
|
- Centralized data fetching and caching
|
|
- Automatic entity updates on data changes
|
|
- Persistent storage via `Store`
|
|
- Quarter-hour boundary refresh scheduling
|
|
|
|
**Price Data Enrichment:**
|
|
|
|
- Raw API data is enriched with statistical analysis
|
|
- Trailing/leading 24h averages calculated per interval
|
|
- Price differences and ratings added
|
|
- All via pure functions in `price_utils.py`
|
|
|
|
**Translation System:**
|
|
|
|
- Dual system: `/translations/` (HA schema) + `/custom_translations/` (extended)
|
|
- Both must stay in sync across all languages (de, en, nb, nl, sv)
|
|
- Async loading at integration setup
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Validate integration structure
|
|
./scripts/release/hassfest
|
|
|
|
# Run all tests
|
|
pytest tests/
|
|
|
|
# Run specific test file
|
|
pytest tests/test_coordinator.py
|
|
|
|
# Run with coverage
|
|
pytest --cov=custom_components.tibber_prices tests/
|
|
```
|
|
|
|
## 📝 Documentation Standards
|
|
|
|
Documentation is organized in two Docusaurus sites:
|
|
|
|
- **User docs** (`docs/user/`): Installation, configuration, usage guides
|
|
- Markdown files in `docs/user/docs/*.md`
|
|
- Navigation managed via `docs/user/sidebars.ts`
|
|
- **Developer docs** (`docs/developer/`): Architecture, patterns, contribution guides
|
|
- Markdown files in `docs/developer/docs/*.md`
|
|
- Navigation managed via `docs/developer/sidebars.ts`
|
|
- **AI guidance**: `AGENTS.md` (patterns, conventions, long-term memory)
|
|
|
|
**Best practices:**
|
|
- Use clear examples and code snippets
|
|
- Keep docs up-to-date with code changes
|
|
- Add new pages to appropriate `sidebars.ts` for navigation
|
|
|
|
## 🤝 Contributing
|
|
|
|
See [CONTRIBUTING.md](https://github.com/jpawlowski/hass.tibber_prices/blob/main/CONTRIBUTING.md) for detailed contribution guidelines, code of conduct, and pull request process.
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the [MIT License](https://github.com/jpawlowski/hass.tibber_prices/blob/main/LICENSE).
|
|
|
|
---
|
|
|
|
**Note:** This documentation is for developers. End users should refer to the [User Documentation](https://jpawlowski.github.io/hass.tibber_prices/user/).
|