# 04 — Community Engagement Plan

**Status:** Final for Milestone 2
**Audience:** FablePool contributors executing the quality-scale uplift program; Home Assistant code owners and core reviewers (shared for transparency)
**Scope:** How we engage the Home Assistant (HA) community while delivering the 12-integration quality-scale uplift defined in docs/01–03 and the per-integration audits in `docs/audits/`.

---

## 1. Guiding Principles

This program only succeeds if the existing community experiences it as **help, not pressure**. Every process decision below derives from five principles:

1. **Maintainers own their integrations.** Code owners listed in `CODEOWNERS` have final say on direction, naming, and architecture within their integration. We propose; they decide. We never route around a code owner who has expressed an objection.
2. **We follow the project's written rules before its unwritten ones — and learn the unwritten ones fast.** ADRs, the developer documentation (developers.home-assistant.io), the integration quality scale, and `hassfest` are the contract. Where reviewer preferences go beyond the written rules, we adopt them without argument and record them in our internal playbook so the next PR doesn't repeat the friction.
3. **Small, reviewable, single-purpose PRs.** Review bandwidth is the scarcest resource in HA core. We optimize for *reviewer minutes*, not contributor convenience.
4. **No surprise scope.** Before starting a multi-PR series on an integration, the plan is posted publicly (issue or Discord thread) and the code owner is offered a veto window.
5. **We absorb the maintenance we create.** Quality-scale uplift adds tests, type hints, and diagnostics that someone must maintain. We commit to a 12-month follow-up window (see §8) and, where welcomed, offer co-code-ownership only after a sustained track record on that integration.

---

## 2. ADR Alignment

All work in this program must be consistent with the Architecture Decision Records in `home-assistant/architecture`. The table below maps the ADR themes that govern our work to concrete program rules.

> ⚠️ **Verification note:** ADRs are referenced here primarily *by topic*. Numbers cited below were taken from memory during drafting and **must be re-verified against the current `home-assistant/architecture` repository** before being quoted in any public PR description or issue. Where we were not confident of a number, only the topic is given.

| ADR topic | Program rule derived from it |
|---|---|
| **Configuration via the UI** (config entries / config flow; widely cited as ADR-0010) | Any remaining YAML-configured platforms in our 12 targets are migrated to config entries **with import flows and deprecation issue registry entries**, never hard-removed. YAML removal follows the documented deprecation cycle (≥ 6 months / 2 stable releases after the import flow ships). |
| **No web scraping / unofficial endpoints** | If an audit gap can only be closed by scraping a device's web UI (relevant risk: `samsungtv`, `fritz` edge features), the gap is documented as *won't-fix* in the audit rather than worked around. All device communication goes through the published dependency library. |
| **External Python dependencies live in standalone, published libraries** | Protocol logic never lands in `homeassistant/components/<domain>/`. Where a gap requires library changes (e.g., `denonavr`, `androidtv`, `broadlink` items in the backlog), we contribute upstream to the library first, get a release cut, then bump `manifest.json`. Backlog items affected by this carry an explicit `upstream-first` dependency tag (see doc 06). |
| **Async-first; no blocking I/O in the event loop** | All library bumps and refactors are audited for `hass.async_add_executor_job` correctness. Sync libraries (e.g., `broadlink`) remain wrapped in executor jobs; we do not attempt async rewrites of upstream libraries inside this program's scope. |
| **Entity naming & `has_entity_name`** | All entity-naming fixes follow the `has_entity_name = True` convention and the entity-naming guidelines in developer docs; we never invent integration-local naming schemes. |
| **Integration quality scale (tiered Bronze/Silver/Gold/Platinum, with `quality_scale.yaml` per integration)** | Every uplift PR series ends with a PR updating `quality_scale.yaml` rule statuses, and the *final* PR of a series requests the formal tier change. We never claim a tier in `manifest.json`/`quality_scale.yaml` ahead of the rules actually being satisfied. |

**Process rule:** If any backlog item appears to require deviating from an ADR, work **stops** on that item and we open (or comment on) a discussion in `home-assistant/architecture` first. We do not ship "temporary" ADR violations.

---

## 3. CODEOWNERS Coordination

### 3.1 Ownership map and contact protocol

Before the first PR on each integration, the assigned contributor:

1. Reads `CODEOWNERS` for the domain and records every listed owner.
2. Reviews the owner's last ~6 months of activity (merged PRs, issue responses) to gauge responsiveness and current direction — e.g., an in-flight refactor we must not collide with.
3. Posts an **uplift proposal** (template in §3.3) as a GitHub issue on `home-assistant/core` titled `[<domain>] Quality scale uplift to <tier> — plan & sequencing`, tagging the code owners, and cross-links it in the `#devs_core` channel of the HA Discord.
4. Waits for the **veto window**: 7 calendar days, or explicit owner acknowledgment, whichever comes first.

### 3.2 Owner-response matrix

| Owner response | Our action |
|---|---|
| Approves / engages | Proceed per agreed sequencing; owner gets first review request on every PR. |
| Requests changes to plan | Revise the plan issue; re-confirm before starting. |
| Objects to part of the plan | Drop the objected items from our backlog for that integration (mark `owner-declined` in doc 06); proceed only with accepted items. |
| Objects to the whole plan | Withdraw from that integration entirely; redistribute effort to the next candidate from the doc-02 selection list. |
| No response in 7 days | Proceed with **Tier-1 items only** (tests, type hints, diagnostics, strings — low-controversy, per §5.2), one PR at a time. Behavioral/UX items (entity renames, flow changes) remain blocked until an owner or core reviewer engages. |
| Integration has **no** code owner | Tier-1 and Tier-2 items proceed under normal core review. If our contributor sustains 3+ merged substantive PRs and ongoing issue triage on the integration, they may volunteer as code owner via the standard `CODEOWNERS` PR — explicitly framed as an offer the core team can decline. |

### 3.3 Uplift proposal template (posted per integration)

```markdown
## Quality scale uplift proposal: <domain>

**Who:** <contributor>, part of a coordinated quality-scale uplift effort
(plan: <link to public program docs>).

**Current state:** <tier or unscored>; audit summary: <3–5 bullet gaps,
mirroring docs/audits/<domain>.md>.

**Proposed target:** <tier>, via N small PRs in this order:
1. <PR 1 — scope, est. diff size>
2. ...

**What we will NOT touch:** <explicit non-goals — e.g., no entity renames,
no library swap, no flow redesign — unless you want them>.

**Asks:** veto/adjust anything above within 7 days; first review on each PR
goes to you. We commit to maintaining what we add for ≥ 12 months.
```

### 3.4 Respecting in-flight work

- We check open PRs and branches touching the domain **before every PR we open**, not just at kickoff.
- If a code owner or any contributor has an open PR overlapping our item, our item is paused and offered as a review + rebase assist on theirs instead.
- We never open a competing PR to an open community PR. If a community PR is stale (> 90 days, author unresponsive after a polite ping), we ask the author and a core reviewer whether adopting it (preserving authorship via co-authored-by or commit retention) is welcome.

---

## 4. PR Sizing & Sequencing Conventions

### 4.1 Hard limits

| Rule | Limit |
|---|---|
| One concern per PR | Exactly one quality-scale rule (or one tightly-coupled pair, e.g., "add reauth flow + its tests") per PR. |
| Diff size target | ≤ 300 changed lines excluding tests and generated files; tests may add more. Soft ceiling 500; anything projected larger is split before opening. |
| Refactor/feature separation | Pure refactors (e.g., move to `DataUpdateCoordinator`) never combined with behavior changes. The refactor PR must be provably behavior-neutral ("no user-visible change" assertion + unchanged snapshot tests where they exist). |
| Mechanical-change isolation | Type-hint-only and string-only PRs contain *zero* logic changes, so they can be reviewed in minutes. |
| Open-PR cap | Max **2 open PRs per integration** and **6 open PRs program-wide** at any time. New PRs in a series open only as predecessors merge (or with explicit reviewer invitation to stack). |

### 4.2 Standard PR series order per integration

Derived from the audit rubric (doc 03); per-integration deviations are recorded in doc 06.

1. **Test scaffolding & fixtures** — get the integration to mockable, deterministic test infrastructure (fixture data, `MockConfigEntry` patterns). No production code changes.
2. **Config-flow test coverage to 100%** — required for any subsequent flow changes; protects everything after it.
3. **Type hints / `strict-typing`** — mechanical; unblocks mypy in CI for the component.
4. **Coordinator/runtime-data modernization** (where audited as needed) — behavior-neutral refactor.
5. **Diagnostics** (with redaction) — small, additive.
6. **Reauth / reconfigure flows** — behavior-adding; depends on 1–2.
7. **Entity naming / `has_entity_name` / device info fixes** — user-visible; requires owner sign-off and, where entity IDs could change, an explicit migration note for the release notes.
8. **Remaining tier rules + `quality_scale.yaml` update + tier-change request.**

### 4.3 PR description discipline

Every PR uses the HA core template fully filled, plus:
- A `Part N of M` series header linking the uplift proposal issue.
- The specific quality-scale rule(s) addressed, by rule key (e.g., `config-flow-test-coverage`, `diagnostics`, `reauthentication-flow`).
- For behavior-neutral refactors: "User-facing change: none" stated explicitly, with the evidence (snapshot tests, unchanged service signatures).
- Paired documentation PR link (`home-assistant.io`) whenever user-facing behavior or setup steps change — opened in the same sitting, cross-linked both directions.
- Test instructions a reviewer without the physical device can follow (which fixtures simulate which device state).

### 4.4 Breaking changes

Default posture: **this program ships zero breaking changes.** Where an audit identified a fix that is unavoidably breaking (flagged per-item in doc 06), the item requires: owner approval, a core-reviewer thumbs-up on the approach *before* coding, a repair issue or deprecation period per current guidelines, and a draft release-notes blurb included in the PR description.

---

## 5. Review-Latency & Escalation Policy

### 5.1 Latency expectations and our obligations

HA core review latency is highly variable (hours to months). Our policy manages our side of the queue without pressuring volunteers:

| Our obligation | SLA on ourselves |
|---|---|
| Respond to review feedback | ≤ 2 business days |
| Resolve merge conflicts / rebase | ≤ 3 days of conflict appearing; otherwise weekly proactive rebase only if the branch has actually conflicted (no churn rebases that reset reviews) |
| CI red on our PR | Fix or convert to draft within 24 hours |
| Reviewer asks for split/scope cut | Comply without debate unless it breaks atomicity; if so, explain once, then defer to reviewer |

### 5.2 Escalation ladder (for stalled PRs)

We classify PRs into two lanes:

- **Lane A (low-controversy):** tests, type hints, diagnostics, strings, coordinator refactors.
- **Lane B (behavioral/UX):** flows, entity naming, anything user-visible.

| Stage | Trigger | Action |
|---|---|---|
| 0 | PR opened | Code owner auto-requested; no additional pings for 14 days. |
| 1 | 14 days, no review | One polite comment on the PR summarizing scope in ≤ 3 sentences ("this is a 120-line test-only PR"). |
| 2 | 28 days, no review | Single mention in Discord `#devs_core` review-request thread per that channel's etiquette (link + one-line scope). Never DM reviewers. |
| 3 | 45 days, no review (Lane A only) | Ask in the monthly community/dev sync channels whether the PR should be re-scoped, split further, or closed. Lane B PRs do not escalate past Stage 2 — if nobody wants to review a behavioral change, that *is* signal, and the item returns to the backlog as `parked-no-review`. |
| Any | Reviewer says "not now" / release freeze | PR goes to draft with a dated note; re-marked ready after the freeze. |

**Anti-patterns we explicitly forbid:** pinging more than once per stage; tagging core team members not already involved; "bump" comments; opening duplicate PRs; soliciting reviews via social media; rebasing solely to surface the PR in activity feeds.

### 5.3 Release-cycle awareness

HA ships monthly with a beta week before each release. Program rules:
- No Lane B PRs opened during beta week; Lane A only, and only if they don't touch code in the release's regression hot spots.
- Any regression traced to a program PR is **our P0**: we ship the fix or revert within 24 hours and proactively offer the revert ourselves rather than waiting to be asked.

---

## 6. Communication Channels & Cadence

| Channel | Use | Cadence |
|---|---|---|
| GitHub issues on `home-assistant/core` | Per-integration uplift proposals; bug reports found during audits (filed individually with reproduction steps, never as omnibus issues) | As needed |
| Discord `#devs_core` | Plan announcements, Stage-2 escalations, quick convention questions | As needed, low volume |
| `home-assistant/architecture` discussions | Anything touching ADR territory | Before coding, always |
| Program status page (this repo) | Public ledger of every PR (link, status, reviewer, latency), per-integration progress vs. audit | Updated weekly |
| Community forum dev category | Monthly digest post of program progress (what merged, what's next, what was declined and why) | Monthly |

All program communication is in the open. No private coordination with reviewers about prioritization.

---

## 7. Conduct, Credit & Tone

- HA Code of Conduct applies; program contributors acknowledge it in writing before their first PR.
- When we adopt or finish someone else's stale work, original authorship is preserved (commits retained or `Co-authored-by`).
- Declined work is recorded without editorializing: the public backlog marks items `owner-declined` with a one-line neutral reason, full stop.
- We do not publish comparative quality rankings of integrations or maintainers. The doc-02 selection methodology is framed around *impact opportunity*, and the audits in `docs/audits/` are framed against the public rubric, never against people.

---

## 8. Sustainability Commitment

Quality uplift that rots is negative-value. The program commits, per integration we touch:

1. **12-month watch window** from the last merged PR: we subscribe to the integration's issue label and triage new issues plausibly related to our changes within 5 business days.
2. **Regression ownership:** any bug bisected to a program commit is fixed by us at P0 priority for the full watch window.
3. **Dependency bumps:** if our work introduced or bumped a library version, we shepherd at least the next two routine bumps or until a maintainer takes over.
4. **Exit report:** at window close, a short public note per integration summarizing delivered tier, open follow-ups, and a handoff list.

---

## 9. Risks & Mitigations (engagement-specific)

| Risk | Likelihood | Mitigation |
|---|---|---|
| Perceived as an outside group "grading" maintainers | Medium | §7 framing rules; proposals always lead with offers, not deficiencies; audits quote the public rubric only. |
| Review bandwidth saturation / goodwill burn | Medium | Hard PR caps (§4.1); Lane B never escalates past Stage 2; we accept `parked-no-review` outcomes. |
| Colliding with the core team's own quality-scale push | Medium | Kickoff issue per integration creates a coordination point; we re-check in-flight work before every PR; we defer to core-driven efforts and convert to review-assists. |
| Entity renames breaking user automations | High impact | Lane B controls, owner sign-off, migration notes, repair issues where applicable; default to *not* renaming when in doubt. |
| Contributor turnover mid-series | Medium | Series state lives in the public backlog (doc 06), not in heads; every PR description carries enough context to be adopted. |