Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
75 lines (58 loc) · 3.7 KB

CONTRIBUTING.md

File metadata and controls

75 lines (58 loc) · 3.7 KB
Raw

Contributing

Thanks for improving SV Dashboard.

Before opening an issue

  • Check the installation guide, entity catalog, and vehicle capability matrix.
  • Confirm the issue also occurs with a supported version of Home Assistant and the upstream Stellantis Vehicles integration.
  • Redact VINs, account IDs, exact home locations, GPS tracks, Notify recipient names, tokens, and raw exports. Do not attach .storage files.
  • Use Discussions for questions, early ideas, compatibility observations, and screenshots; reserve Issues for reproducible bugs and mature feature proposals.

See the community guide for the full reporting and discussion rules.

Development principles

  • Preserve the upstream boundary: this project consumes Home Assistant entities from Stellantis Vehicles and does not call the Stellantis API.
  • Never hard-code a vehicle, VIN, entity ID, image URL, user, or notify target.
  • New dashboard behaviour must handle unavailable or absent upstream entities.
  • Add or update every user-facing string across all 18 supported languages in the same change, including config/options/entity text, frontend labels, notifications, push messages and Logbook text; see localisation.
  • Keep third-party HACS cards as dependencies. Do not vendor or modify them.
  • Use third-party product and brand names only where needed to describe compatibility or interoperability. Do not add manufacturer logos, official badges, brand artwork, promotional imagery, or other protected visual assets unless the applicable permission or licence is clearly documented. See TRADEMARKS.md.

Verification

Run the validation commands in AGENTS.md. Runtime acceptance uses the designated Home Assistant instance and must deploy the exact candidate develop SHA. Record that SHA and the result in the GitHub Issue. Test a newly created config entry when onboarding/config-flow behavior changed and verify the automatically created dashboard after frontend changes.

Branches and stable promotion

All implementation, documentation, tests and candidate version changes are committed to develop. Do not develop or hotfix directly on main.

develop is the integration/acceptance branch. The designated Home Assistant instance may intentionally run an exact develop commit for real-world validation. main is the last accepted, publishable state.

After runtime acceptance and maintainer approval, main is moved forward to the exact validated develop SHA using a fast-forward promotion. Do not squash, rebase or cherry-pick the accepted change set during that promotion; the stable commit must remain the same commit that was tested. Tags and GitHub releases are created from that promoted main SHA.

At a healthy release boundary main and develop are identical. Between releases, develop may be ahead of main; the two branches must not contain independent lines of feature/fix commits. If they diverge, reconcile the histories before the next release.

See Branch and deployment workflow for the complete contract.

Pull requests and review

Describe the user-visible change, the upstream entity/capability it relies on, and how it was tested. Update documentation whenever setup, an entity, a calculation, a notification, or a dependency changes.

Pull requests may be used for review of develop work, but the stable promotion itself must preserve the exact accepted commit SHA. Do not create a new squash/rebase commit merely to move validated code to main.