Skip to content

getting-started.md

Latest commit

 

History

History
153 lines (107 loc) · 5.2 KB

getting-started.md

File metadata and controls

153 lines (107 loc) · 5.2 KB
Raw

Getting Started

This is the primary onboarding guide for contributors to the Hitachi Yutaki Home Assistant integration. It covers environment setup, running the project locally, and the workflow for submitting changes.

Prerequisites

  • Python 3.13+
  • uv -- Python package manager (used via Makefile)
  • git

Setup

  1. Fork and clone the repository:
git clone https://github.com/<your-username>/hass-hitachi_yutaki.git
cd hass-hitachi_yutaki
  1. Run the full project setup (installs dependencies and pre-commit hooks):
make setup
  1. Verify everything works:
make check && make test

If both commands pass, your environment is ready.

Running Home Assistant Locally

Start a development instance of Home Assistant with the integration loaded:

make ha-run

Home Assistant will be available at http://localhost:8123.

To use a custom port, add the following to config/configuration.yaml:

http:
  server_port: 9125

Project Structure

hass-hitachi_yutaki/
├── custom_components/hitachi_yutaki/
│   ├── domain/            # Pure business logic (no HA dependencies)
│   ├── adapters/          # Bridges domain with Home Assistant
│   ├── entities/          # Domain-driven entity organization
│   ├── api/               # Modbus communication layer
│   ├── profiles/          # Heat pump model profiles
│   └── translations/      # Language files
├── tests/                 # Test suite (pytest)
│   ├── domain/            # Domain layer tests (pure Python)
│   └── profiles/          # Profile detection tests
└── docs/                  # Developer documentation

The codebase follows a hexagonal (ports and adapters) architecture. See Architecture for a detailed breakdown of each layer and the design principles behind them.

Make Targets

Run make help to list all available targets. Here is a reference of the most common ones:

Target Description
make install Install all dependencies (dev included)
make setup Full project setup (deps + pre-commit hooks + system libs)
make upgrade-deps Upgrade all deps (HA version follows pytest-homeassistant-custom-component)
make lint Run ruff linter with auto-fix
make format Run ruff formatter
make check Run all code quality checks (lint + format)
make test Run all tests
make test-domain Run domain layer tests only (pure Python, no HA)
make test-coverage Run tests with coverage report
make ha-run Start a local HA dev instance with debug config
make ha-upgrade Temporary HA upgrade (reset by make install)
make ha-dev-branch Temporary HA dev branch (reset by make install)
make ha-version Temporary HA specific version (reset by make install)
make bump Bump version (last numeric segment)
make version Show current version

Note: The Home Assistant version in the dev environment is controlled by pytest-homeassistant-custom-component via the lockfile. Use make upgrade-deps to update it. The ha-upgrade, ha-dev-branch, and ha-version targets are temporary overrides for ad-hoc testing -- make install restores the lockfile version.

Running Tests

# Run the full test suite
make test

# Run domain layer tests only (pure Python, fast, no HA mocks)
make test-domain

# Run tests with coverage report
make test-coverage

Domain tests (tests/domain/) exercise the business logic in isolation and run significantly faster than integration-level tests because they do not require Home Assistant.

Code Quality

Code style is enforced by Ruff (linting and formatting) with a Home Assistant-specific ruleset defined in pyproject.toml under [tool.ruff]. Pre-commit hooks run Ruff automatically on every commit.

Before pushing, always run:

make check

This runs both the linter (with auto-fix) and the formatter in a single command.

Your First Contribution

  1. Create a branch from main:
git checkout main && git pull
git checkout -b feat/my-feature

  1. Make your changes, following the hexagonal architecture conventions.

  2. Update the changelog -- add an entry under [Unreleased] in CHANGELOG.md using Keep a Changelog format.

  3. Run quality checks and tests:

make check && make test
  1. Commit using conventional commit format:
git commit -m "feat: add new sensor for X"
  1. Open a pull request targeting the main branch. PRs are squash-merged, so each PR becomes a single commit on main. All CI checks (tests, lint, HACS/hassfest validation) must pass before merge.

Further Reading