Improve trigger descriptions #157643

emontnemery · 2025-12-01T16:17:32Z

Proposed change

Improve trigger descriptions as discussed with @jlpouffier

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

This PR fixes or closes issue: fixes #
This PR is related to issue:
Link to documentation pull request:
Link to developer documentation pull request:
Link to frontend pull request:

Checklist

I understand the code I am submitting and can explain how it works.
The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
The code has been formatted using Ruff (ruff format homeassistant tests)
Tests have been added to verify that the new code works.
Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

emontnemery · 2025-12-01T16:18:07Z

homeassistant/components/assist_satellite/strings.json

  },
  "title": "Assist satellite",
  "triggers": {
    "idle": {


The keys for assist_satellite are not consistent with other domains

emontnemery · 2025-12-01T16:19:00Z

homeassistant/components/lawn_mower/strings.json

  },
  "title": "Lawn mower",
  "triggers": {
    "docked": {


should we change this to "returned_to_dock", or is "docked" good enough?

Docked is good.
You explained it too me, we do not enforce the temporary state "Returning to dock". So it's for both. IT's good 👍🏻

emontnemery · 2025-12-01T16:19:16Z

homeassistant/components/lawn_mower/strings.json

-      "name": "When a lawn mower has docked"
+      "name": "Lawn mower returned to dock"
    },
    "errored": {


should we change this to "encounted_error", or is "errored" good enough?

emontnemery · 2025-12-01T16:19:40Z

homeassistant/components/vacuum/strings.json

  },
  "title": "Vacuum",
  "triggers": {
    "docked": {


Same comment as for lawn mower

emontnemery · 2025-12-01T16:19:46Z

homeassistant/components/vacuum/strings.json

-      "name": "When a vacuum cleaner has docked"
+      "name": "Vacuum returned to dock"
    },
    "errored": {


Same comment as for lawn mower

emontnemery · 2025-12-01T16:20:54Z

homeassistant/components/alarm_control_panel/strings.json

  "triggers": {
    "armed": {
-      "description": "Triggers when an alarm is armed.",
+      "description": "Triggers when one or several alarms are armed, regardless of the mode.",


I discussed this a bit with @jlpouffier.
He first suggested "Triggers when one or several alarms are armed, regardless of the mode.", then I suggested to drop the "get", and in the PR I changed to "are".
Edit: Changed back to "get"

Why not replace 'several' with 'more' to simplify the wording?

OK with several >>> more.

Not a strong push, i'm also perfectly fine with several for that particular PR.
We've been struggling with wording for so long that I'm more willing to push something out the finish line now :D

jbouwh

LGTM,
Thanks @emontnemery 👍

emontnemery · 2025-12-01T16:54:40Z

I want @jlpouffier to review before this is merged

emontnemery · 2025-12-01T16:55:37Z

I hid the bot review comments because I don't think they were helpful

homeassistant/components/assist_satellite/strings.json

homeassistant/components/fan/strings.json

emontnemery · 2025-12-01T18:36:27Z

@MartinHjelmare there have been a lot of discussions about the wording.
I think the pattern "Triggers when one or several fans turn on" is good, I'm not sure if we have considered that variant. @jlpouffier ?

MartinHjelmare · 2025-12-01T18:38:04Z

Grammar isn't really something to discuss. It's either correct or wrong. What to discuss is what tense to use for the description.

emontnemery · 2025-12-01T18:50:57Z

OK, let's not discuss grammar here then. Closing for now.

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

homeassistant/components/assist_satellite/strings.json

jlpouffier · 2025-12-01T20:15:29Z

I'm ok with @MartinHjelmare proposal
~~After + Past tense instead of When + Present~~
~~It is both~~

~~Grammatically correct~~
~~Aligned with the technical names of the triggers.~~

~~Triggers after a light turned on. Perfectly understandable.~~

EDIT: on hold, discussing with Martin .. Not sure I fully understand the nuances

OK, discussing with @MartinHjelmare ✅

It's actually After + Present that is correct.
Triggers after one or many lights turn on

I'm ok with that, i'll review now with that in mind

homeassistant/components/alarm_control_panel/strings.json

homeassistant/components/lawn_mower/strings.json

homeassistant/components/text/strings.json

homeassistant/components/vacuum/strings.json

jlpouffier · 2025-12-01T21:41:32Z

@emontnemery I made lots of comments, but only the first one is actually something I'd like to see changed ☺️

I made a proposal alighed with other triggers

homeassistant/components/assist_satellite/strings.json

Co-authored-by: Martin Hjelmare <[email protected]>

frenck

Thanks, @emontnemery 👍

../Frenck

Blogging my personal ramblings at frenck.dev

Co-authored-by: Martin Hjelmare <[email protected]>

Improve trigger descriptions

b42bfc8

Copilot AI review requested due to automatic review settings December 1, 2025 16:17

emontnemery requested review from a team, arturpragacz, bdraco, jbouwh and synesthesiam as code owners December 1, 2025 16:17

home-assistant bot added cla-signed code-quality core labels Dec 1, 2025

Copilot started reviewing on behalf of emontnemery December 1, 2025 16:18 View session

Copilot finished reviewing on behalf of emontnemery December 1, 2025 16:19

emontnemery commented Dec 1, 2025

View reviewed changes

This comment was marked as off-topic.

Sign in to view

Adjust

bbcd2b1

jbouwh approved these changes Dec 1, 2025

View reviewed changes

emontnemery added the second-opinion-wanted Add this label when a reviewer needs a second opinion from another member. label Dec 1, 2025

MartinHjelmare reviewed Dec 1, 2025

View reviewed changes

homeassistant/components/assist_satellite/strings.json Outdated Show resolved Hide resolved

homeassistant/components/assist_satellite/strings.json Outdated Show resolved Hide resolved

homeassistant/components/fan/strings.json Outdated Show resolved Hide resolved

MartinHjelmare marked this pull request as draft December 1, 2025 17:15

Adjust language

deb8692

emontnemery closed this Dec 1, 2025

emontnemery reopened this Dec 1, 2025

emontnemery added 2 commits December 1, 2025 19:58

Adjust more

bc2fb7a

Adjust more

d69ff82

emontnemery requested a review from Copilot December 1, 2025 19:16

Copilot started reviewing on behalf of emontnemery December 1, 2025 19:16 View session

Copilot finished reviewing on behalf of emontnemery December 1, 2025 19:18

Copilot AI reviewed Dec 1, 2025

View reviewed changes

homeassistant/components/assist_satellite/strings.json Outdated Show resolved Hide resolved

Adjust language

895cb66

jlpouffier suggested changes Dec 1, 2025

View reviewed changes

Make language more cumbersome

5014466

emontnemery marked this pull request as ready for review December 2, 2025 07:01

emontnemery requested a review from jlpouffier December 2, 2025 07:01

emontnemery mentioned this pull request Dec 2, 2025

Add occupancy binary sensor triggers #157631

Merged

21 tasks

MartinHjelmare reviewed Dec 2, 2025

View reviewed changes

homeassistant/components/assist_satellite/strings.json Outdated Show resolved Hide resolved

MartinHjelmare approved these changes Dec 2, 2025

View reviewed changes

MartinHjelmare removed the second-opinion-wanted Add this label when a reviewer needs a second opinion from another member. label Dec 2, 2025

Update homeassistant/components/assist_satellite/strings.json

eb8a527

Co-authored-by: Martin Hjelmare <[email protected]>

frenck approved these changes Dec 2, 2025

View reviewed changes

frenck merged commit 393be71 into dev Dec 2, 2025
66 checks passed

frenck deleted the improve_trigger_descriptions branch December 2, 2025 10:08

frenck added this to the 2025.12.0 milestone Dec 2, 2025

frenck added the cherry-picked label Dec 2, 2025

frenck pushed a commit that referenced this pull request Dec 2, 2025

Improve trigger descriptions (#157643)

ebc9060

Co-authored-by: Martin Hjelmare <[email protected]>

github-actions bot locked and limited conversation to collaborators Dec 3, 2025

Uh oh!

Improve trigger descriptions #157643

Improve trigger descriptions #157643

Uh oh!

Conversation

emontnemery commented Dec 1, 2025

Proposed change

Type of change

Additional information

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emontnemery Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as off-topic.

Uh oh!

jbouwh left a comment

Choose a reason for hiding this comment

Uh oh!

emontnemery commented Dec 1, 2025

Uh oh!

emontnemery commented Dec 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

emontnemery commented Dec 1, 2025

Uh oh!

MartinHjelmare commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

emontnemery commented Dec 1, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

jlpouffier commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jlpouffier commented Dec 1, 2025

Uh oh!

Uh oh!

frenck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

emontnemery Dec 1, 2025 •

edited

Loading

MartinHjelmare commented Dec 1, 2025 •

edited

Loading

jlpouffier commented Dec 1, 2025 •

edited

Loading