Development & Releasing

For contributors and the curious. The runtime design is in Architecture.

Repo layout

custom_components/suunto_app/
  __init__.py        entry setup, runtime_data, platforms
  api.py             HTTP client (ASKO + NDJSON, gzip detection, login)
  auth.py            login signing pipeline (ported from suuntool)
  coordinator.py     the two coordinators, mapping, derived metrics, stats import
  metrics.py         pure CTL/ATL/TSB, ACWR, baselines, readiness
  statistics.py      external-statistics bucketing + import
  sensor.py          56 sensor descriptions
  calendar.py        workouts calendar entity
  config_flow.py     login / reauth / options
  const.py           constants, look-back windows, activityId map
  manifest.json      domain, version, HA minimum, after_dependencies
  strings.json       UI + entity translations
  brand/             inline brand icons

Design principles

• metrics.py is pure - no Home Assistant or network imports - so the training-load and recovery maths are unit-tested deterministically. Keep new computation there.
• Two coordinators, split by cadence (live vs history). New sensors declare a source (fast/daily); don't add heavy fetches to the fast path.
• Map fields once, in the coordinator. Sensors read already-converted values via value_fn. Unit conversions (the Data & Units gotchas) live in the coordinator, not the sensor.
• Fail soft. A flaky single stream should leave its section empty, not blank everything; only a true auth error escalates to reauth.

Validation

CI runs hassfest (manifest correctness) and HACS validation. Before opening a PR:

• Keep manifest.json valid and the version in sync with the release tag (see below).
• Verify any new MDI icon name actually exists - invalid names render blank with no error. Check https://raw.githubusercontent.com/Templarian/MaterialDesign-SVG/master/svg/<name>.svg returns 200.
• The HA minimum (2024.12.0) gates which APIs you can use - see the list in Architecture.

Releasing (HACS update detection)

HACS detects updates from GitHub Releases (tags) - not the manifest alone and not plain commits. To ship:

1. Bump manifest.json version.
2. Push.
3. Create a GitHub Release with a tag that matches the manifest version.

Two channels

Channel	Branch	Release type	Tag
Production	main	normal release ("Latest")	X.Y.Z
Beta	beta	pre-release	X.Y.ZbN (PEP 440 beta, e.g. 1.0.12b1)

HACS only offers pre-releases to users who enable "Show beta versions"; everyone else stays on the latest stable. Typical flow: commit to beta → bump manifest to ...bN → cut a pre-release → when stable, merge beta → main, bump to X.Y.Z, cut a normal release, then start the next beta.

Update the changelog

Add an entry to CHANGELOG.md (mirrored on the Changelog wiki page) for every user-visible change.