Proposal how user contributions to the device database could work

[mkerstner]

The Preview Edition is read-only today. You can browse and search devices, but you cannot correct a wrong category, add a proper product image, or fix a model name. Anonymized submissions from Home Assistant instances tell us which devices exist and what they talk to, but they cannot tell us any of that. Only people can.

So we have written up a first proposal for how contributions could work, and we would like to pick it apart with you before we build anything. Going with our next milestones on the roadmap OpenHomeFoundation/roadmap#87

📄 Read the proposal (open for comments, feel free to comment inline as well)

What it covers

1. Where contributions are stored. A public Git repository as the data store, one file per field, symlinks instead of moves, sharded device directories.
2. How you would contribute. An edit mode on the device page for a small starting set of fields (image, model, model ID, category), with sources attached per field, resulting in one pull request per changed value.
3. How contributions get moderated. A GitHub bot enforcing merge rules, with per-field merge intervals so that riskier edits stay open longer. This section is deliberately the least finished.

The choices we would most like feedback on

• Git as the data store, not a database. It gives us history, transparency, and distribution for free, and it means the website is never the only way to contribute. Is the tradeoff in browsing and querying acceptable to you?
• One PR per changed field. Keeps a conflict on one field from blocking edits to others, at the cost of more PRs in flight. Better ideas welcome.
• Rules and automation over human review. We do not want to be a bottleneck, and a moderation funnel would reintroduce exactly the bias the database is meant to avoid. Which edits do you think genuinely need a human, and which should merge on a timer?
  Starting narrow. Four editable fields to begin with, expanding from there. Which field would you want to fix first?

Related discussions

• #152 Stage 3: Accounts and editing covers the design and UX side of accounts and editing. The flow in this proposal is meant to fit what is being explored there, so please keep UI-specific feedback in that thread where it makes sense.
• The overarching roadmap opportunity is OpenHomeFoundation/roadmap#87, which is where the bigger picture around user contributions lives.
• You can also join us in the device database channel on Discord if you would rather talk it through.

[mkerstner]

Based on feedback and active discussions during our Lisbon summit (slides here for reference https://docs.google.com/presentation/d/1ZQ8cApaYi3pi73Z-sUN4lUCCadpzuSCb-2D3Qz7lkaE/edit?slide=id.g35c9c97dd26_0_0#slide=id.g35c9c97dd26_0_0)

here are the main takeaways:

1. Direction to proceed with Git as central storage seems fine 👍
2. Proposed Git structure makes sense 👍
3. Proposed Git merge and moderation flows make sense 👍

We'll iron out details as we proceed but there's a good common understanding to proceed while enabling both - convenient editing through the public website and editing using PRs directly.

We'll continue to track in this roadmap opportunity: OpenHomeFoundation/roadmap#87