Skip to content

Contributing

Help improve Voice Assistant Persistent Timers!

Ways to Contribute

  • Report bugs - File issues with reproduction steps
  • Suggest features - Open discussions for new ideas
  • Add devices - Contribute configurations for new hardware
  • Improve docs - Fix errors, add examples, clarify steps
  • Share translations - Add custom sentences in other languages

Development Setup

Prerequisites

  • Python 3.13+
  • uv package manager
  • Home Assistant instance for testing

Clone Repository

git clone https://github.com/Djelibeybi/voice-assistant-persistent-timers.git
cd voice-assistant-persistent-timers

Install Tools

uv tool install esphome

Extract Configurations

python3 scripts/extract_configs.py

Validate Configs

./scripts/validate_configs.sh

Code Style

YAML

  • 2-space indentation
  • No trailing whitespace
  • Descriptive comments for complex logic
  • Group related configuration sections

Python

  • Follow PEP 8
  • Use type hints
  • Document functions with docstrings
  • User ruff for formatting and linting

Markdown

  • One sentence per line (for better diffs)
  • Use ATX-style headers (#)
  • Include alt text for images
  • Use fenced code blocks with language hints

Literate Programming Format

Device configurations use literate programming. Code blocks are embedded in markdown documentation.

Code Block Markers

# file: esphome/examples/device-name.yaml
# section: substitutions
substitutions:
  timer_area: "kitchen"
  • # file: - Output file path
  • # section: - Section identifier for ordering

Section Order

Sections are assembled in this order:

  1. substitutions
  2. esphome
  3. esp32
  4. packages
  5. external_components
  6. api
  7. ota
  8. wifi
  9. logger
  10. i2c
  11. spi
  12. audio
  13. wake_word
  14. sensor
  15. text_sensor
  16. touchscreen
  17. binary_sensor
  18. button
  19. switch
  20. globals
  21. script
  22. image
  23. font
  24. color
  25. display

Example Device Doc

# My Device

Description of the device.

## Hardware Overview

| Feature | Value    |
| ------- | -------- |
| Board   | ESP32-S3 |

## Substitutions

\`\`\`yaml

# file: esphome/examples/my-device.yaml

# section: substitutions

substitutions:
timer_area: "area_name"
\`\`\`

## ESPHome Core

\`\`\`yaml

# file: esphome/examples/my-device.yaml

# section: esphome

esphome:
name: my-device
\`\`\`

Pull Request Process

Before Submitting

  1. Test your changes - Verify on actual hardware if possible
  2. Run validation - ./scripts/validate_configs.sh
  3. Update docs - If adding features, document them
  4. Check formatting - No trailing whitespace, consistent indentation

PR Guidelines

  1. One feature or device per PR - Easier to review
  2. Clear title - Describe what changes
  3. Description - Explain why and how
  4. Link issues - Reference related issues

Commit Messages

Follow conventional commits:

feat: add support for ESP32-S3-BOX-Lite
fix: correct timer sensor attribute name
docs: clarify area naming requirements
chore: update ESPHome version requirement

Review Process

  1. Maintainer reviews within 1-2 weeks
  2. Address feedback with new commits
  3. Squash when approved
  4. Maintainer merges

Adding a New Device

Step 1: Gather Information

Document the hardware:

  • Board/chip model
  • Display type and resolution
  • Touch controller (if any)
  • Audio codec
  • GPIO pin assignments

Step 2: Create Device Doc

Copy docs/devices/_template.md and fill in sections:

cp docs/devices/_template.md docs/devices/my-new-device.md

Step 3: Extract and Test

python3 scripts/extract_configs.py
esphome config esphome/examples/my-new-device.yaml
esphome run esphome/examples/my-new-device.yaml

Step 4: Verify Timer Functionality

Test checklist:

  • Timer starts with voice command
  • Display shows progress
  • Alarm sounds on completion
  • Timer persists after restart
  • Cancel/pause/resume work

Step 5: Submit PR

Include:

  • Device documentation file
  • Any required package updates
  • Update to README.md device table
  • Test results

Reporting Bugs

Good Bug Report

## Description

Timer display doesn't update when timer is paused.

## Steps to Reproduce

1. Start a 5-minute timer
2. Say "Pause the timer"
3. Display still shows countdown instead of "paused"

## Expected Behavior

Display should show "(paused)" indicator.

## Actual Behavior

Display continues showing countdown numbers.

## Environment

- ESPHome: 2025.5.0
- Home Assistant: 2024.5.0
- Device: ESP32-S3-BOX-3
- Timer area: kitchen

## Logs

[Relevant log excerpts]

## Configuration

[Relevant config snippets - no secrets!]

Feature Requests

Good Feature Request

## Feature

Support for multiple timers per area.

## Use Case

Cooking often requires multiple simultaneous timers
(e.g., pasta water and sauce).

## Proposed Solution

1. Add timer naming support: "Set a pasta timer for 10 minutes"
2. Display multiple progress bars
3. Query by name: "How much time on the pasta timer?"

## Alternatives Considered

- Using timers from different areas
- Using HA dashboard instead

## Would you work on this?

Yes, I can contribute an implementation.

Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help newcomers learn
  • Assume good intent

License

Contributions are licensed under CC BY-NC-SA 4.0.

By contributing, you agree to license your work under these terms.

Questions?

  • Open a discussion on GitHub
  • Check existing issues first
  • Include relevant context