ha-legacy-gsm-sms Development

Development guidelines for maintaining the ha-legacy-gsm-sms Home Assistant addon repository, which provides legacy GSM SMS notifications via GSM-modem using HACS or HA Add-on options.

Repository Structure

This repository contains multiple addon variants with intentional differences:

**CRITICAL**: These variants have intentional differences that must be preserved.

Development Guidelines

1. File Editing Rules

**NEVER copy entire files between addons.** Always make surgical, line-by-line edits to preserve custom settings.

Before editing any config file:

1. Read the file first using `read_file` or `git show HEAD:path`

2. Identify what needs to change - only those specific lines

3. Make surgical edits - change only what's necessary

4. Verify with diff - check that only intended changes were made

2. Test Addon Custom Settings (addon-test-current/)

The test addon has these **intentional differences** that must be preserved:

**config.yaml**:

**support.py**:

3. Tuned Values - Do NOT Change

These values have been specifically tuned for this project and differ from upstream:

4. Syncing Features Between Addons

When adding a new feature to both production and test addons:

1. Implement in production addon first (`addon-gsm-gateway/`)

2. For Python files (`mqtt_publisher.py`, `run.py`): These CAN be synced (except `support.py`)

3. For `config.yaml`: Make **individual line edits** - never copy the whole file

4. Always verify test addon customizations are preserved after changes

5. Version Bumping

Both should be bumped together when features are added.

6. Feature Implementation Checklist

When adding a new SMS feature, it must be implemented in ALL these places:

**Don't mark complete until all four are done.**

7. Phone Number Validation

Phone numbers can contain: `+`, digits, spaces, `-`, `(`, `)`, `,`

The `+` character can appear **anywhere** (not just at the start) because multiple international numbers are comma-separated: `+1234567890,+0987654321`

**Correct regex**: `^[\+\d\s\-\(\),]*$`

**Wrong regex**: `^\+?[\d\s\-\(\),]*$` (only allows + at start)

8. Validation Before Completion

Before marking a task as complete:

1. Run Python syntax check on all modified `.py` files

2. Test the logic with edge cases (multiple values, empty values, special characters)

3. Verify with `git diff` that only intended changes were made

4. Check that both production AND test addons are updated (if applicable)

5. Confirm documentation matches the implementation

9. When in Doubt

If unsure whether a file has custom settings or special handling:

10. Upstream Reference

This project is based on [PavelVe/hassio-addons](https://github.com/PavelVe/hassio-addons).

When syncing upstream features, always credit the source in CHANGELOG.md.

Examples

Adding a New Feature

```markdown

1. Implement in addon-gsm-gateway/mqtt_publisher.py

2. Add corresponding REST API endpoint in addon-gsm-gateway/run.py

3. Document the feature in README.md

4. Add entry to CHANGELOG.md

5. Make surgical edits to addon-test-current/ files (NOT full file copy)

6. Verify test addon custom settings preserved

7. Bump versions: 2.14.0 (production), 2.14.0-test (test)

8. Run validation checks

```

Syncing a Bug Fix

```markdown

1. Fix bug in addon-gsm-gateway/mqtt_publisher.py

2. Read addon-test-current/mqtt_publisher.py

3. Apply same fix with surgical edit

4. Verify with git diff

5. Test both variants

```

Constraints