hass.tibber_prices/CONTRIBUTING.md

Contributing to Tibber Prices Integration

Thank you for your interest in contributing! This document provides guidelines for contributing to this Home Assistant custom integration.

📋 Table of Contents

• Getting Started
• Development Process
• Coding Standards
• Submitting Changes
• Documentation

For detailed developer documentation, see docs/development/.

Note: This project is developed with extensive AI assistance (GitHub Copilot, Claude). If you're also using AI tools, check AGENTS.md for patterns and conventions that ensure consistency.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork:

   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"

See Development Setup for detailed instructions.

Development Process

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

2. Make Changes

• Follow the Coding Guidelines
• Keep changes focused and atomic
• Update documentation if needed

3. Test Your Changes

# Lint and format
./scripts/lint

# Start development environment
./scripts/develop

# Run tests (if available)
pytest tests/

4. Commit Your Changes

We use Conventional Commits format:

<type>(<scope>): <short summary>

<detailed description>

Impact: <user-visible effects>

Types: feat, fix, docs, refactor, chore, test

Example:

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 AGENTS.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:

./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 for complete details.

Documentation

Documentation is organized in two Docusaurus sites:

• User docs (docs/user/): Installation, configuration, usage guides
  • Markdown files in docs/user/docs/*.md
  • Navigation via docs/user/sidebars.ts
• Developer docs (docs/developer/): Architecture, patterns, contribution guides
  • Markdown files in docs/developer/docs/*.md
  • Navigation via docs/developer/sidebars.ts

When adding new documentation:

1. Place file in appropriate docs/*/docs/ directory
2. Add to corresponding sidebars.ts for navigation
3. Update translations when changing translations/en.json (update ALL language files)

Reporting Bugs

Report bugs via GitHub Issues.

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
• Read Copilot Instructions for patterns
• Search existing issues
• Open a new issue

License

By contributing, you agree that your contributions will be licensed under its MIT License.