jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-03-30 05:13:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: restructure documentation and add AI development disclosure

Browse source 
Created professional documentation structure:

**User Documentation (docs/user/):**
- README.md: Documentation hub with quick start guide
- Placeholder files for future content migration:
  * installation.md, configuration.md, sensors.md
  * services.md, automation-examples.md, troubleshooting.md

**Developer Documentation (docs/development/):**
- README.md: Comprehensive contributor guide with AI section
- setup.md: DevContainer and environment setup
- architecture.md: Code structure overview
- testing.md: Testing guidelines
- coding-guidelines.md: Style guide and critical patterns
- release-management.md: Complete release workflow documentation

**AI Development Disclosure:**
- README.md: "🤖 Development Note" section before license
  * Honest disclosure about extensive AI assistance
  * Quality assurance measures mentioned
  * Invitation for bug reports with positive tone
- docs/development/README.md: Detailed AI section
  * What AI handles (patterns, generation, refactoring)
  * Benefits (rapid development, consistency)
  * Limitations (edge cases, complex patterns)
  * Quality assurance process
- CONTRIBUTING.md: Brief AI note with practical tip

**Updated:**
- README.md: Simplified to landing page with documentation links
- CONTRIBUTING.md: Modernized with new docs structure
- copilot-instructions.md: Added documentation organization section

Impact: Clear separation of user vs. developer documentation following
open-source best practices. Transparent about AI-assisted development
approach without being defensive. Scalable structure for future growth.
This commit is contained in:
Julian Pawlowski 2025-11-09 14:25:27 +00:00
parent e08fd60070
commit df79afc87e
16 changed files with 1164 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

182
.github/copilot-instructions.md vendored
View file

@ -16,7 +16,14 @@ _Note: When proposing significant updates to this file, update the metadata abov
When working with the codebase, Copilot MUST actively maintain consistency between this documentation and the actual code: When working with the codebase, Copilot MUST actively maintain consistency between this documentation and the actual code:
**Scope:** "This documentation" and "this file" refer specifically to `.github/copilot-instructions.md`. This does NOT include user-facing documentation like `README.md`, `/docs/`, or comments in code. Those serve different purposes and are maintained separately. **Scope:** "This documentation" and "this file" refer specifically to `.github/copilot-instructions.md`. This does NOT include user-facing documentation like `README.md`, `/docs/user/`, or comments in code. Those serve different purposes and are maintained separately.
**Documentation Organization:**
- **This file** (`.github/copilot-instructions.md`): AI/Developer long-term memory, patterns, conventions
- **`docs/user/`**: End-user guides (installation, configuration, usage examples)
- **`docs/development/`**: Contributor guides (setup, architecture, release management)
- **`README.md`**: Project overview with links to detailed documentation
**Important:** `AGENTS.md` and `CLAUDE.md` in the repository root are **symlinks** to this file (`.github/copilot-instructions.md`). All three files are automatically synchronized through the symlink - do NOT attempt to edit them separately or check if they're in sync. Always edit only `.github/copilot-instructions.md`. **Important:** `AGENTS.md` and `CLAUDE.md` in the repository root are **symlinks** to this file (`.github/copilot-instructions.md`). All three files are automatically synchronized through the symlink - do NOT attempt to edit them separately or check if they're in sync. Always edit only `.github/copilot-instructions.md`.
@ -228,6 +235,13 @@ custom_components/tibber_prices/
- All scripts in `./scripts/` automatically use the correct `.venv` - All scripts in `./scripts/` automatically use the correct `.venv`
- No need to manually activate venv or specify Python path - No need to manually activate venv or specify Python path
- Examples: `./scripts/lint`, `./scripts/develop`, `./scripts/lint-check` - Examples: `./scripts/lint`, `./scripts/develop`, `./scripts/lint-check`
- Release management: `./scripts/prepare-release`, `./scripts/generate-release-notes`
**Release Note Backends (auto-installed in DevContainer):**
- **Rust toolchain**: Minimal Rust installation via DevContainer feature
- **git-cliff**: Template-based release notes (fast, reliable, installed via cargo in `scripts/setup`)
- Manual grep/awk parsing as fallback (always available)
**When generating shell commands:** **When generating shell commands:**
@ -654,6 +668,172 @@ The "Impact:" section bridges technical commits and future release notes:
- Impact sections provide user context (for release notes) - Impact sections provide user context (for release notes)
- Future AI translates into user-friendly format - Future AI translates into user-friendly format
### Release Notes Generation
**Multiple Options Available:**
1. **Helper Script** (recommended, foolproof)
- Script: `./scripts/prepare-release VERSION`
- Bumps manifest.json version → commits → creates tag locally
- You review and push when ready
- Example: `./scripts/prepare-release 0.3.0`
2. **Auto-Tag Workflow** (safety net)
- Workflow: `.github/workflows/auto-tag.yml`
- Triggers on manifest.json changes
- Automatically creates tag if it doesn't exist
- Prevents "forgot to tag" mistakes
3. **Local Script** (testing, preview)
- Script: `./scripts/generate-release-notes [FROM_TAG] [TO_TAG]`
- Parses Conventional Commits between tags
- Supports multiple backends (auto-detected):
- **AI-powered**: GitHub Copilot CLI (best, context-aware)
- **Template-based**: git-cliff (fast, reliable)
- **Manual**: grep/awk fallback (always works)
4. **GitHub UI Button** (manual, PR-based)
- Uses `.github/release.yml` configuration
- Click "Generate release notes" when creating release
- Works best with PRs that have labels
- Direct commits appear in "Other Changes" category
5. **CI/CD Automation** (automatic on tag push)
- Workflow: `.github/workflows/release.yml`
- Triggers on version tags (v1.0.0, v2.1.3, etc.)
- Uses git-cliff backend (AI disabled in CI)
- Filters out version bump commits automatically
- Creates GitHub release automatically
**Recommended Release Workflow:**
```bash
# Step 1: Prepare release (bumps manifest.json + creates tag)
./scripts/prepare-release 0.3.0
# Step 2: Review changes
git log -1 --stat
git show v0.3.0
# Step 3: Push when ready
git push origin main v0.3.0
# Done! CI/CD creates release automatically
```
**Alternative: Manual Bump (with Auto-Tag Safety Net):**
```bash
# 1. Bump manifest.json manually
vim custom_components/tibber_prices/manifest.json # "version": "0.3.0"
git commit -am "chore(release): bump version to 0.3.0"
git push
# 2. Auto-Tag workflow detects manifest.json change → creates tag
# 3. Release workflow creates GitHub release
```
**Using the Local Script:**
```bash
# Generate from latest tag to HEAD
./scripts/generate-release-notes
# Generate between specific tags
./scripts/generate-release-notes v1.0.0 v1.1.0
# Force specific backend
RELEASE_NOTES_BACKEND=manual ./scripts/generate-release-notes
# Disable AI (use in CI/CD)
USE_AI=false ./scripts/generate-release-notes
```
**Backend Selection Logic:**
1. If `$RELEASE_NOTES_BACKEND` set → use that backend
2. Else if in CI/CD (`$CI` or `$GITHUB_ACTIONS`) → skip AI, use git-cliff or manual
3. Else if `USE_AI=false` → skip AI, use git-cliff or manual
4. Else if GitHub Copilot CLI available (`copilot` command) → use AI (best quality, smart grouping)
5. Else if git-cliff available → use template-based (fast, reliable, 1:1 commit mapping)
6. Else → use manual grep/awk parsing (always works)
**Backend Comparison:**
- **GitHub Copilot CLI** (`copilot`):
- ✅ AI-powered semantic understanding
- ✅ Smart grouping of related commits into single release notes
- ✅ Interprets "Impact:" sections for user-friendly descriptions
- ✅ Multiple commits can be combined with all links: ([hash1](url1), [hash2](url2))
- ⚠️ Uses premium request quota
- ⚠️ Output may vary between runs
- **git-cliff** (template-based):
- ✅ Fast and consistent
- ✅ 1:1 commit to release note line mapping
- ✅ Highly configurable via `cliff.toml`
- ❌ No semantic understanding
- ❌ Cannot intelligently group related commits
- **manual** (grep/awk):
- ✅ Always available (no dependencies)
- ✅ Basic commit categorization
- ❌ No commit grouping
- ❌ Basic formatting only
**Output Format:**
All backends produce GitHub-flavored Markdown with consistent structure:
```markdown
## 🎉 New Features
- **scope**: Description ([commit_hash](link))
User-visible impact from "Impact:" section
- **scope**: Combined description ([hash1](link1), [hash2](link2)) # AI backend only
Multiple related commits grouped together
```
## 🐛 Bug Fixes
- **scope**: Description ([commit_hash](link))
User-visible impact
## 📚 Documentation
...
````
**Installing Optional Backends:**
```bash
# git-cliff (fast, reliable, used in CI/CD)
# Auto-installed in DevContainer via scripts/setup
# See: https://git-cliff.org/docs/installation
cargo install git-cliff # or download binary from releases
````
**When to Use Which:**
- **GitHub Button**: When working with PRs, quick manual releases
- **Local Script**: Before committing to test release notes, manual review needed
- **CI/CD**: Automatic releases on tag push (production workflow)
**Format Requirements:**
- **HACS**: No specific format required, uses GitHub releases as-is
- **Home Assistant**: No specific format required for custom integrations
- **Markdown**: Standard GitHub-flavored Markdown supported
- **HTML**: Can include `<ha-alert>` tags for special notices (HA update entities only)
**Validate JSON files:** **Validate JSON files:**
```bash ```bash

168
CONTRIBUTING.md
View file

@ -1,61 +1,151 @@
# Contribution guidelines # Contributing to Tibber Prices Integration
Contributing to this project should be as easy and transparent as possible, whether it's: Thank you for your interest in contributing! This document provides guidelines for contributing to this Home Assistant custom integration.
- Reporting a bug ## 📋 Table of Contents
- Discussing the current state of the code
- Submitting a fix
- Proposing new features
## Github is used for everything - [Getting Started](#getting-started)
- [Development Process](#development-process)
- [Coding Standards](#coding-standards)
- [Submitting Changes](#submitting-changes)
- [Documentation](#documentation)
Github is used to host code, to track issues and feature requests, as well as accept pull requests. For detailed developer documentation, see [docs/development/](docs/development/).
Pull requests are the best way to propose changes to the codebase. > **Note:** This project is developed with extensive AI assistance (GitHub Copilot, Claude). If you're also using AI tools, check [`.github/copilot-instructions.md`](/.github/copilot-instructions.md) for patterns and conventions that ensure consistency.
1. Fork the repo and create your branch from `main`. ## Getting Started
2. Run `scripts/bootstrap` to install dependencies and pre-commit hooks.
3. If you've changed something, update the documentation.
4. Make sure your code lints (using `scripts/lint`).
5. Test your contribution.
6. Issue that pull request!
## Any contributions you make will be under the MIT Software License 1. **Fork the repository** on GitHub
2. **Clone your fork**:
```bash
git clone https://github.com/YOUR_USERNAME/hass.tibber_prices.git
cd hass.tibber_prices
```
3. **Open in DevContainer** (recommended):
- Open in VS Code
- Click "Reopen in Container" when prompted
- Or manually: `Ctrl+Shift+P` → "Dev Containers: Reopen in Container"
In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern. See [Development Setup](docs/development/setup.md) for detailed instructions.
## Report bugs using Github's [issues](../../issues) ## Development Process
GitHub issues are used to track public bugs. ### 1. Create a Branch
Report a bug by [opening a new issue](../../issues/new/choose); it's that easy!
## Write bug reports with detail, background, and sample code ```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description
```
**Great Bug Reports** tend to have: ### 2. Make Changes
- A quick summary and/or background - Follow the [Coding Guidelines](docs/development/coding-guidelines.md)
- Steps to reproduce - Keep changes focused and atomic
- Be specific! - Update documentation if needed
- Give sample code if you can.
- What you expected would happen
- What actually happens
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
People *love* thorough bug reports. I'm not even kidding. ### 3. Test Your Changes
## Use a Consistent Coding Style ```bash
# Lint and format
./scripts/lint
Use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. Run `scripts/lint` to format your code before submitting. # Start development environment
./scripts/develop
## Test your code modification # Run tests (if available)
pytest tests/
```
This custom component is based on [integration_blueprint template](https://github.com/ludeeus/integration_blueprint). ### 4. Commit Your Changes
It comes with development environment in a container, easy to launch We use **Conventional Commits** format:
if you use Visual Studio Code. With this container you will have a stand alone
Home Assistant instance running and already configured with the included ```
[`configuration.yaml`](./config/configuration.yaml) <type>(<scope>): <short summary>
file.
<detailed description>
Impact: <user-visible effects>
```
**Types:** `feat`, `fix`, `docs`, `refactor`, `chore`, `test`
**Example:**
```bash
git commit -m "feat(sensors): add daily average price sensor
Added new sensor that calculates average price for the entire day.
Impact: Users can now track daily average prices for cost analysis."
```
See `.github/copilot-instructions.md` section "Git Workflow Guidance" for detailed guidelines.
## Submitting Changes
### Pull Request Process
1. **Push your branch** to your fork
2. **Create a Pull Request** on GitHub with:
- Clear title describing the change
- Detailed description with context
- Reference related issues (`Fixes #123`)
3. **Wait for review** and address feedback
### PR Requirements
- ✅ Code passes `./scripts/lint-check`
- ✅ No breaking changes (or clearly documented)
- ✅ Translations updated for all languages
- ✅ Commit messages follow Conventional Commits
- ✅ Changes tested in Home Assistant
## Coding Standards
### Code Style
- **Formatter/Linter**: Ruff (enforced automatically)
- **Max line length**: 120 characters
- **Python version**: 3.13+
Always run before committing:
```bash
./scripts/lint
```
### Key Patterns
- Use `dt_util` from `homeassistant.util` for all datetime operations
- Load translations asynchronously at integration setup
- Enrich price data before exposing to entities
- Follow Home Assistant entity naming conventions
See [Coding Guidelines](docs/development/coding-guidelines.md) for complete details.
## Documentation
- **User guides**: Place in `docs/user/` (installation, configuration, usage)
- **Developer guides**: Place in `docs/development/` (architecture, patterns)
- **Update translations**: When changing `translations/en.json`, update ALL language files
## Reporting Bugs
Report bugs via [GitHub Issues](../../issues/new/choose).
**Great bug reports include:**
- Quick summary and background
- Steps to reproduce (be specific!)
- Expected vs. actual behavior
- Sample code/logs if applicable
## Questions?
- Check [Developer Documentation](docs/development/)
- Read [Copilot Instructions](.github/copilot-instructions.md) for patterns
- Search [existing issues](https://github.com/jpawlowski/hass.tibber_prices/issues)
- Open a [new issue](https://github.com/jpawlowski/hass.tibber_prices/issues/new)
## License ## License

81
README.md
View file

@ -12,7 +12,13 @@ A Home Assistant integration that provides advanced price information and rating
![Tibber Price Information & Ratings](images/logo.png) ![Tibber Price Information & Ratings](images/logo.png)
## Features ## 📖 Documentation
- **[User Guide](docs/user/)** - Installation, configuration, and usage guides
- **[Developer Guide](docs/development/)** - Contributing, architecture, and release process
- **[Changelog](https://github.com/jpawlowski/hass.tibber_prices/releases)** - Release history and notes
## ✨ Features
- **Quarter-Hourly Price Data**: Access detailed 15-minute interval pricing (192 data points across yesterday/today/tomorrow) - **Quarter-Hourly Price Data**: Access detailed 15-minute interval pricing (192 data points across yesterday/today/tomorrow)
- **Current and Next Interval Prices**: Get real-time price data in both major currency (€, kr) and minor units (ct, øre) - **Current and Next Interval Prices**: Get real-time price data in both major currency (€, kr) and minor units (ct, øre)
@ -26,39 +32,32 @@ A Home Assistant integration that provides advanced price information and rating
- **Diagnostic Sensors**: Monitor data freshness and availability - **Diagnostic Sensors**: Monitor data freshness and availability
- **Reliable API Usage**: Uses only official Tibber [`priceInfo`](https://developer.tibber.com/docs/reference#priceinfo) and [`priceInfoRange`](https://developer.tibber.com/docs/reference#subscription) endpoints - no legacy APIs. Price ratings and statistics are calculated locally for maximum reliability and future-proofing. - **Reliable API Usage**: Uses only official Tibber [`priceInfo`](https://developer.tibber.com/docs/reference#priceinfo) and [`priceInfoRange`](https://developer.tibber.com/docs/reference#subscription) endpoints - no legacy APIs. Price ratings and statistics are calculated locally for maximum reliability and future-proofing.
## Installation ## 🚀 Quick Start
### HACS Installation (Recommended) ### Installation
1. Ensure [HACS](https://hacs.xyz/) is installed in your Home Assistant instance 1. **Install via HACS** (recommended)
2. Go to HACS > Integrations > Click the three dots in the top right > Custom repositories - Add as custom repository: `https://github.com/jpawlowski/hass.tibber_prices`
3. Add this repository URL: `https://github.com/jpawlowski/hass.tibber_prices` - Search for "Tibber Price Information & Ratings"
4. Click "Add" - Click "Install"
5. Search for "Tibber Price Information & Ratings" in the Integrations tab
6. Click "Install"
7. Restart Home Assistant
### Manual Installation 2. **Add Integration**
- Go to Settings → Devices & Services
- Click "+ Add Integration"
- Search for "Tibber Price Information & Ratings"
1. Copy the `custom_components/tibber_prices` directory from this repository into your Home Assistant's `custom_components` directory 3. **Configure**
2. Restart Home Assistant - Enter your Tibber API token ([get one here](https://developer.tibber.com/settings/access-token))
- Select your Tibber home
- Configure price thresholds (optional)
## Configuration 4. **Start Using!**
- 30+ sensors available (key sensors enabled by default)
- Use in automations, dashboards, and scripts
### Requirements 📖 **[Full Installation Guide →](docs/user/installation.md)**
- A Tibber account with an active subscription ## 📊 Available Entities
- A Tibber API access token (obtain from [developer.tibber.com](https://developer.tibber.com/settings/access-token))
### Setup Process
1. Go to **Settings** > **Devices & Services** in your Home Assistant UI
2. Click the **+ ADD INTEGRATION** button in the bottom right
3. Search for "Tibber Price Information & Ratings"
4. Enter your Tibber API access token when prompted
5. Click "Submit"
## Available Entities
The integration provides **30+ sensors** across different categories. Key sensors are enabled by default, while advanced sensors can be enabled as needed. The integration provides **30+ sensors** across different categories. Key sensors are enabled by default, while advanced sensors can be enabled as needed.
@ -275,26 +274,42 @@ template:
Price at {{ timestamp }}: {{ price }} ct/kWh Price at {{ timestamp }}: {{ price }} ct/kWh
``` ```
📖 **[View all sensors and attributes →](docs/user/sensors.md)**
### Custom Services ### Custom Services
The integration provides custom services for advanced use cases: The integration provides custom services for advanced use cases:
- `tibber_prices.get_price` - Fetch price data for specific days/times (useful for scripts) - `tibber_prices.get_price` - Fetch price data for specific days/times
- `tibber_prices.get_apexcharts_data` - Get formatted data for ApexCharts cards - `tibber_prices.get_apexcharts_data` - Get formatted data for ApexCharts cards
- `tibber_prices.get_apexcharts_yaml` - Generate complete ApexCharts card configuration - `tibber_prices.get_apexcharts_yaml` - Generate complete ApexCharts configurations
- `tibber_prices.refresh_user_data` - Manually refresh account information - `tibber_prices.refresh_user_data` - Manually refresh account information
See the Services tab in Home Assistant Developer Tools for detailed documentation and parameters. 📖 **[Service documentation and examples →](docs/user/services.md)**
### ApexCharts Integration ### ApexCharts Integration
The integration includes built-in support for creating beautiful price visualization cards. Use the `get_apexcharts_yaml` service to generate card configurations automatically. The integration includes built-in support for creating beautiful price visualization cards. Use the `get_apexcharts_yaml` service to generate card configurations automatically.
## Contributing 📖 **[ApexCharts examples →](docs/user/automation-examples.md#apexcharts-cards)**
If you want to contribute to this project, please read the [Contributing Guidelines](CONTRIBUTING.md). ## 🤝 Contributing
## License Contributions are welcome! Please read the [Contributing Guidelines](CONTRIBUTING.md) and [Developer Guide](docs/development/) before submitting pull requests.
### For Contributors
- **[Developer Setup](docs/development/setup.md)** - Get started with DevContainer
- **[Architecture Guide](docs/development/architecture.md)** - Understand the codebase
- **[Release Management](docs/development/release-management.md)** - Release process and versioning
## 🤖 Development Note
This integration is developed with extensive AI assistance (GitHub Copilot, Claude, and other AI tools). While AI enables rapid development and helps implement complex features, it's possible that some edge cases or subtle bugs may exist that haven't been discovered yet. If you encounter any issues, please [open an issue](https://github.com/jpawlowski/hass.tibber_prices/issues/new) - we'll work on fixing them (with AI help, of course! 😊).
The integration is actively maintained and benefits from AI's ability to quickly understand and implement Home Assistant patterns, maintain consistency across the codebase, and handle complex data transformations. Quality is ensured through automated linting (Ruff), Home Assistant's type checking, and real-world testing.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

147
docs/development/README.md Normal file
View file

@ -0,0 +1,147 @@
# Developer Documentation
This section contains documentation for contributors and maintainers of the Tibber Prices integration.
## 📚 Developer Guides
- **[Setup](setup.md)** - DevContainer, environment setup, and dependencies
- **[Architecture](architecture.md)** - Code structure, patterns, and conventions
- **[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
## 🤖 AI Documentation
The main AI/Copilot documentation is in [`.github/copilot-instructions.md`](../../.github/copilot-instructions.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 `copilot-instructions.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 `copilot-instructions.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` (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. **Test your changes** in the running Home Assistant instance
8. **Commit using Conventional Commits** format
9. **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
- `lint` - Auto-fix code issues with ruff
- `lint-check` - Check code without modifications (CI mode)
- `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.py # Sensor platform
├── binary_sensor.py # Binary sensor platform
├── 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
# 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
- **User-facing docs** go in `docs/user/`
- **Developer docs** go in `docs/development/`
- **AI guidance** goes in `.github/copilot-instructions.md`
- Use clear examples and code snippets
- Keep docs up-to-date with code changes
## 🤝 Contributing
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines, code of conduct, and pull request process.
## 📄 License
This project is licensed under [LICENSE](../../LICENSE).
---
**Note:** This documentation is for developers. End users should refer to the [User Documentation](../user/).

21
docs/development/architecture.md Normal file
View file

@ -0,0 +1,21 @@
# Architecture
> **Note:** This guide is under construction. For now, please refer to `.github/copilot-instructions.md` for detailed architecture information.
## Core Components
### Data Flow
1. `TibberPricesApiClient` - GraphQL API client
2. `TibberPricesDataUpdateCoordinator` - Update orchestration & caching
3. Price enrichment functions - Statistical calculations
4. Entity platforms - Sensors and binary sensors
5. Custom services - API endpoints
### Key Patterns
- **Dual translation system**: `/translations/` (HA schema) + `/custom_translations/` (extended)
- **Price enrichment**: 24h trailing/leading averages, ratings, differences
- **Quarter-hour precision**: Entity updates on 00/15/30/45 boundaries
- **Intelligent caching**: User data (24h), price data (calendar day validation)
See `.github/copilot-instructions.md` "Architecture Overview" section for complete details.

53
docs/development/coding-guidelines.md Normal file
View file

@ -0,0 +1,53 @@
# Coding Guidelines
> **Note:** For complete coding standards, see `.github/copilot-instructions.md`.
## Code Style
- **Formatter/Linter**: Ruff (replaces Black, Flake8, isort)
- **Max line length**: 120 characters
- **Max complexity**: 25 (McCabe)
- **Target**: Python 3.13
Run before committing:
```bash
./scripts/lint
```
## Import Order
1. Python stdlib (specific types only)
2. Third-party (`homeassistant.*`, `aiohttp`)
3. Local (`.api`, `.const`)
## Critical Patterns
### Time Handling
Always use `dt_util` from `homeassistant.util`:
```python
from homeassistant.util import dt as dt_util
price_time = dt_util.parse_datetime(starts_at)
price_time = dt_util.as_local(price_time) # Convert to HA timezone
now = dt_util.now()
```
### Translation Loading
```python
# In __init__.py async_setup_entry:
await async_load_translations(hass, "en")
await async_load_standard_translations(hass, "en")
```
### Price Data Enrichment
Always enrich raw API data:
```python
from .price_utils import enrich_price_info_with_differences
enriched = enrich_price_info_with_differences(
price_info_data,
thresholds,
)
```
See `.github/copilot-instructions.md` for complete guidelines.

361
docs/development/release-management.md Normal file
View file

@ -0,0 +1,361 @@
# Release Notes Generation
This project supports **three ways** to generate release notes from conventional commits, plus **automatic version management**.
## 🚀 Quick Start: Preparing a Release
**Recommended workflow (automatic & foolproof):**
```bash
# 1. Use the helper script to prepare release
./scripts/prepare-release 0.3.0
# This will:
# - Update manifest.json version to 0.3.0
# - Create commit: "chore(release): bump version to 0.3.0"
# - Create tag: v0.3.0
# - Show you what will be pushed
# 2. Review and push when ready
git push origin main v0.3.0
# 3. CI/CD automatically:
# - Detects the new tag
# - Generates release notes (excluding version bump commit)
# - Creates GitHub release
```
**If you forget to bump manifest.json:**
```bash
# Just edit manifest.json manually and commit
vim custom_components/tibber_prices/manifest.json # "version": "0.3.0"
git commit -am "chore(release): bump version to 0.3.0"
git push
# Auto-Tag workflow detects manifest.json change and creates tag automatically!
# Then Release workflow kicks in and creates the GitHub release
```
---
## 📋 Release Options
### 1. GitHub UI Button (Easiest)
Use GitHub's built-in release notes generator:
1. Go to [Releases](https://github.com/jpawlowski/hass.tibber_prices/releases)
2. Click "Draft a new release"
3. Select your tag
4. Click "Generate release notes" button
5. Edit if needed and publish
**Uses:** `.github/release.yml` configuration
**Best for:** Quick releases, works with PRs that have labels
**Note:** Direct commits appear in "Other Changes" category
---
### 2. Local Script (Intelligent)
Run `./scripts/generate-release-notes` to parse conventional commits locally.
**Automatic backend detection:**
```bash
# Generate from latest tag to HEAD
./scripts/generate-release-notes
# Generate between specific tags
./scripts/generate-release-notes v1.0.0 v1.1.0
# Generate from tag to HEAD
./scripts/generate-release-notes v1.0.0 HEAD
```
**Force specific backend:**
```bash
# Use AI (GitHub Copilot CLI)
RELEASE_NOTES_BACKEND=copilot ./scripts/generate-release-notes
# Use git-cliff (template-based)
RELEASE_NOTES_BACKEND=git-cliff ./scripts/generate-release-notes
# Use manual parsing (grep/awk fallback)
RELEASE_NOTES_BACKEND=manual ./scripts/generate-release-notes
```
**Disable AI** (useful for CI/CD):
```bash
USE_AI=false ./scripts/generate-release-notes
```
#### Backend Priority
The script automatically selects the best available backend:
1. **GitHub Copilot CLI** - AI-powered, context-aware (best quality)
2. **git-cliff** - Fast Rust tool with templates (reliable)
3. **Manual** - Simple grep/awk parsing (always works)
In CI/CD (`$CI` or `$GITHUB_ACTIONS`), AI is automatically disabled.
#### Installing Optional Backends
**In DevContainer (automatic):**
git-cliff is automatically installed when the DevContainer is built:
- **Rust toolchain**: Installed via `ghcr.io/devcontainers/features/rust:1` (minimal profile)
- **git-cliff**: Installed via cargo in `scripts/setup`
Simply rebuild the container (VS Code: "Dev Containers: Rebuild Container") and git-cliff will be available.
**Manual installation (outside DevContainer):**
**git-cliff** (template-based):
```bash
# See: https://git-cliff.org/docs/installation
# macOS
brew install git-cliff
# Cargo (all platforms)
cargo install git-cliff
# Manual binary download
wget https://github.com/orhun/git-cliff/releases/latest/download/git-cliff-x86_64-unknown-linux-gnu.tar.gz
tar -xzf git-cliff-*.tar.gz
sudo mv git-cliff-*/git-cliff /usr/local/bin/
```
---
### 3. CI/CD Automation
Automatic release notes on tag push.
**Workflow:** `.github/workflows/release.yml`
**Triggers:** Version tags (`v1.0.0`, `v2.1.3`, etc.)
```bash
# Create and push a tag to trigger automatic release
git tag v1.0.0
git push origin v1.0.0
# GitHub Actions will:
# 1. Detect the new tag
# 2. Generate release notes using git-cliff
# 3. Create a GitHub release automatically
```
**Backend:** Uses `git-cliff` (AI disabled in CI for reliability)
---
## 📝 Output Format
All methods produce GitHub-flavored Markdown with emoji categories:
```markdown
## 🎉 New Features
- **scope**: Description ([abc1234](link-to-commit))
## 🐛 Bug Fixes
- **scope**: Description ([def5678](link-to-commit))
## 📚 Documentation
- **scope**: Description ([ghi9012](link-to-commit))
## 🔧 Maintenance & Refactoring
- **scope**: Description ([jkl3456](link-to-commit))
## 🧪 Testing
- **scope**: Description ([mno7890](link-to-commit))
```
---
## 🎯 When to Use Which
| Method | Use Case | Pros | Cons |
|--------|----------|------|------|
| **Helper Script** | Normal releases | Foolproof, automatic | Requires script |
| **Auto-Tag Workflow** | Forgot script | Safety net, automatic tagging | Still need manifest bump |
| **GitHub Button** | Manual quick release | Easy, no script | Limited categorization |
| **Local Script** | Testing release notes | Preview before release | Manual process |
| **CI/CD** | After tag push | Fully automatic | Needs tag first |
---
## 🔄 Complete Release Workflows
### Workflow A: Using Helper Script (Recommended)
```bash
# Step 1: Prepare release (all-in-one)
./scripts/prepare-release 0.3.0
# Step 2: Review changes
git log -1 --stat
git show v0.3.0
# Step 3: Push when ready
git push origin main v0.3.0
# Done! CI/CD creates the release automatically
```
**What happens:**
1. Script bumps manifest.json → commits → creates tag locally
2. You push commit + tag together
3. Release workflow sees tag → generates notes → creates release
---
### Workflow B: Manual (with Auto-Tag Safety Net)
```bash
# Step 1: Bump version manually
vim custom_components/tibber_prices/manifest.json
# Change: "version": "0.3.0"
# Step 2: Commit
git commit -am "chore(release): bump version to 0.3.0"
git push
# Step 3: Wait for Auto-Tag workflow
# GitHub Actions automatically creates v0.3.0 tag
# Then Release workflow creates the release
```
**What happens:**
1. You push manifest.json change
2. Auto-Tag workflow detects change → creates tag automatically
3. Release workflow sees new tag → creates release
---
### Workflow C: Manual Tag (Old Way)
```bash
# Step 1: Bump version
vim custom_components/tibber_prices/manifest.json
git commit -am "chore(release): bump version to 0.3.0"
# Step 2: Create tag manually
git tag v0.3.0
git push origin main v0.3.0
# Release workflow creates release
```
**What happens:**
1. You create and push tag manually
2. Release workflow creates release
3. Auto-Tag workflow skips (tag already exists)
---
## ⚙️ Configuration Files
- `scripts/prepare-release` - Helper script to bump version + create tag
- `.github/workflows/auto-tag.yml` - Automatic tag creation on manifest.json change
- `.github/workflows/release.yml` - Automatic release on tag push
- `.github/release.yml` - GitHub UI button configuration
- `cliff.toml` - git-cliff template (filters out version bumps)
---
## 🛡️ Safety Features
### 1. **Version Validation**
Both helper script and auto-tag workflow validate version format (X.Y.Z).
### 2. **No Duplicate Tags**
- Helper script checks if tag exists (local + remote)
- Auto-tag workflow checks if tag exists before creating
### 3. **Atomic Operations**
Helper script creates commit + tag locally. You decide when to push.
### 4. **Version Bumps Filtered**
Release notes automatically exclude `chore(release): bump version` commits.
### 5. **Rollback Instructions**
Helper script shows how to undo if you change your mind.
---
## 🐛 Troubleshooting
**"Tag already exists" error:**
```bash
# Local tag
git tag -d v0.3.0
# Remote tag (only if you need to recreate)
git push origin :refs/tags/v0.3.0
```
**Manifest version doesn't match tag:**
This shouldn't happen with the new workflows, but if it does:
```bash
# 1. Fix manifest.json
vim custom_components/tibber_prices/manifest.json
# 2. Amend the commit
git commit --amend -am "chore(release): bump version to 0.3.0"
# 3. Move the tag
git tag -f v0.3.0
git push -f origin main v0.3.0
```
**Auto-tag didn't create tag:**
Check workflow runs in GitHub Actions. Common causes:
- Tag already exists remotely
- Invalid version format in manifest.json
- manifest.json not in the commit that was pushed
---
## 🔍 Format Requirements
**HACS:** No specific format required, uses GitHub releases as-is
**Home Assistant:** No specific format required for custom integrations
**Markdown:** Standard GitHub-flavored Markdown supported
**HTML:** Can include `<ha-alert>` tags if needed
---
## 💡 Tips
1. **Conventional Commits:** Use proper commit format for best results:
```
feat(scope): Add new feature
Detailed description of what changed.
Impact: Users can now do X and Y.
```
2. **Impact Section:** Add `Impact:` in commit body for user-friendly descriptions
3. **Test Locally:** Run `./scripts/generate-release-notes` before creating release
4. **AI vs Template:** GitHub Copilot CLI provides better descriptions, git-cliff is faster and more reliable
5. **CI/CD:** Tag push triggers automatic release - no manual intervention needed

53
docs/development/setup.md Normal file
View file

@ -0,0 +1,53 @@
# Development Setup
> **Note:** This guide is under construction. For now, please refer to `.github/copilot-instructions.md` for detailed setup information.
## Prerequisites
- VS Code with Dev Container support
- Docker installed and running
- GitHub account (for Tibber API token)
## Quick Setup
```bash
# Clone the repository
git clone https://github.com/jpawlowski/hass.tibber_prices.git
cd hass.tibber_prices
# Open in VS Code
code .
# Reopen in DevContainer (VS Code will prompt)
# Or manually: Ctrl+Shift+P → "Dev Containers: Reopen in Container"
```
## Development Environment
The DevContainer includes:
- Python 3.13 with `.venv` at `/home/vscode/.venv/`
- `uv` package manager (fast, modern Python tooling)
- Home Assistant development dependencies
- Ruff linter/formatter
- Git, GitHub CLI, Node.js, Rust toolchain
## Running the Integration
```bash
# Start Home Assistant in debug mode
./scripts/develop
```
Visit http://localhost:8123
## Making Changes
```bash
# Lint and format code
./scripts/lint
# Check-only (CI mode)
./scripts/lint-check
```
See `.github/copilot-instructions.md` for detailed patterns and conventions.

33
docs/development/testing.md Normal file
View file

@ -0,0 +1,33 @@
# Testing
> **Note:** This guide is under construction.
## Running Tests
```bash
# Run all tests
pytest tests/
# Run specific test file
pytest tests/test_coordinator.py
# Run with coverage
pytest --cov=custom_components.tibber_prices tests/
```
## Manual Testing
```bash
# Start development environment
./scripts/develop
```
Then test in Home Assistant UI:
- Configuration flow
- Sensor states and attributes
- Services
- Translation strings
## Test Guidelines
Coming soon...

46
docs/user/README.md Normal file
View file

@ -0,0 +1,46 @@
# User Documentation
Welcome to Tibber Prices! This integration provides enhanced electricity price data from Tibber with quarter-hourly precision, statistical analysis, and intelligent ratings.
## 📚 Documentation
- **[Installation](installation.md)** - How to install via HACS and configure the integration
- **[Configuration](configuration.md)** - Setting up your Tibber API token and price thresholds
- **[Sensors](sensors.md)** - Available sensors, their states, and attributes
- **[Services](services.md)** - Custom services and how to use them
- **[Automation Examples](automation-examples.md)** - Ready-to-use automation recipes
- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions
## 🚀 Quick Start
1. **Install via HACS** (add as custom repository)
2. **Add Integration** in Home Assistant → Settings → Devices & Services
3. **Enter Tibber API Token** (get yours at [developer.tibber.com](https://developer.tibber.com/))
4. **Configure Price Thresholds** (optional, defaults work for most users)
5. **Start Using Sensors** in automations, dashboards, and scripts!
## ✨ Key Features
- **Quarter-hourly precision** - 15-minute intervals for accurate price tracking
- **Statistical analysis** - Trailing/leading 24h averages for context
- **Price ratings** - LOW/NORMAL/HIGH classification based on your thresholds
- **Best hour detection** - Automatic detection of cheapest/peak hours
- **ApexCharts integration** - Custom services for beautiful price charts
- **Multi-currency support** - EUR, NOK, SEK with proper minor units (ct, øre, öre)
## 🔗 Useful Links
- [GitHub Repository](https://github.com/jpawlowski/hass.tibber_prices)
- [Issue Tracker](https://github.com/jpawlowski/hass.tibber_prices/issues)
- [Release Notes](https://github.com/jpawlowski/hass.tibber_prices/releases)
- [Home Assistant Community](https://community.home-assistant.io/)
## 🤝 Need Help?
- Check the [Troubleshooting Guide](troubleshooting.md)
- Search [existing issues](https://github.com/jpawlowski/hass.tibber_prices/issues)
- Open a [new issue](https://github.com/jpawlowski/hass.tibber_prices/issues/new) if needed
---
**Note:** These guides are for end users. If you want to contribute to development, see the [Developer Documentation](../development/).

15
docs/user/automation-examples.md Normal file
View file

@ -0,0 +1,15 @@
# Automation Examples
> **Note:** This guide is under construction.
## Price-Based Automations
Coming soon...
## Best Hour Detection
Coming soon...
## ApexCharts Cards
Coming soon...

15
docs/user/configuration.md Normal file
View file

@ -0,0 +1,15 @@
# Configuration
> **Note:** This guide is under construction. For now, please refer to the [main README](../../README.md) for configuration instructions.
## Initial Setup
Coming soon...
## Configuration Options
Coming soon...
## Price Thresholds
Coming soon...

15
docs/user/installation.md Normal file
View file

@ -0,0 +1,15 @@
# Installation
> **Note:** This guide is under construction. For now, please refer to the [main README](../../README.md) for installation instructions.
## HACS Installation (Recommended)
Coming soon...
## Manual Installation
Coming soon...
## Configuration
Coming soon...

19
docs/user/sensors.md Normal file
View file

@ -0,0 +1,19 @@
# Sensors
> **Note:** This guide is under construction. For now, please refer to the [main README](../../README.md) for available sensors.
## Core Price Sensors
Coming soon...
## Statistical Sensors
Coming soon...
## Rating Sensors
Coming soon...
## Diagnostic Sensors
Coming soon...

11
docs/user/services.md Normal file
View file

@ -0,0 +1,11 @@
# Services
> **Note:** This guide is under construction. For now, please refer to the Services tab in Home Assistant Developer Tools.
## Available Services
Coming soon...
## Examples
Coming soon...

17
docs/user/troubleshooting.md Normal file
View file

@ -0,0 +1,17 @@
# Troubleshooting
> **Note:** This guide is under construction.
## Common Issues
Coming soon...
## Debug Logging
Coming soon...
## Getting Help
- Check [existing issues](https://github.com/jpawlowski/hass.tibber_prices/issues)
- Open a [new issue](https://github.com/jpawlowski/hass.tibber_prices/issues/new) with detailed information
- Include logs, configuration, and steps to reproduce