Contributing

Contributing

The integration's quality depends on real-user feedback and contributions from the HA community.

Ways to help (no coding required)

• File issues for bugs, missing features, unclear docs → GitHub Issues
• Improve this wiki — most pages are editable by collaborators. Open an issue if you spot something wrong.
• Share screenshots of dashboards you've built — GitHub Discussions → Show & Tell
• Translate strings — custom_components/smartghar/translations/ (English exists; other languages welcome)

Code contributions

# Clone the repo
git clone https://github.com/Techposts/smartghar-homeassistant.git
cd smartghar-homeassistant

# Install in your HA dev environment
ln -s "$(pwd)/custom_components/smartghar" \
      ~/.homeassistant/custom_components/smartghar

# Restart HA, make changes, iterate

Tests run with pytest; HACS + hassfest validation runs in CI on every push.

Code style

• Follow HA's development guidelines
• Type hints everywhere
• ruff + black for formatting

Commit message style

Conventional commits:

feat: <new feature>
fix: <bug fix>
docs: <documentation only>
refactor: <code change without behaviour change>
chore: <tooling, deps, build>

Subject under ~70 chars. Body explains why, not what (the diff shows what).

Protocol-spec changes

The hub-side HTTP/WebSocket API at docs/protocol/v1.md is the contract this integration depends on, and that third-party clients implement against. Breaking changes need:

1. A GitHub Discussion thread proposing the change
2. A 2-week comment window
3. A new schema version bump (e.g. v1 → v2) with a deprecation window for v1

Non-breaking additions (new fields, new endpoints, new optional behaviours) can go straight to a PR.

Blueprint contributions

If you build a custom automation that others might want, drop it as a YAML file under blueprints/automation/smartghar/<name>.yaml. Patterns to follow:

• Full blueprint: header with name, description, domain: automation, source_url, input (with selectors)
• mode: single (or parallel: max: N if appropriate)
• Sensible defaults so a non-technical user can install with mostly-default settings
• Reference the integration's entity types (sensor.smartghar_*, event.smartghar_*, etc.) but make the trigger entity an input so users can select which tank

See the existing low-water-alert.yaml and refill-confirmation.yaml for examples.

Lovelace card contributions

Native Lovelace cards are not on the roadmap for this integration (community card ecosystem already covers the visual need). But if you build a custom card that uses our entities and want to share it:

• Publish in a separate HACS-Frontend repo
• Open a GitHub Discussion linking to it
• We'll feature good ones in Lovelace-Beautification

Documentation contributions

Wiki pages and docs/*.md files in the repo both welcome PRs. Wiki edits go to <repo>.wiki.git; in-repo doc edits go through normal PR review.

For wiki: each page = one concept, ~100-200 lines. Cross-link via [[Page-Name]] (kebab-case wiki page filenames).

Code of conduct

Be kind. Discuss ideas, not people. We're building this for water-tank owners — most of them aren't programmers and we owe their patience back to each other.

Maintainers

• @Techposts (project lead)

If you're contributing actively and want maintainer rights, open a Discussion proposing it. Same applies for trusted reviewers.

License

Layer	License
Code (custom_components/smartghar/*, blueprints, services)	MIT
Protocol spec (docs/protocol/)	Apache-2.0

By contributing code, you agree to license your contribution under MIT. By contributing to the protocol spec, you agree to license your contribution under Apache-2.0.