PR-based contribution path with the same validation #184

Summary

As a contributor comfortable with Git, I want to propose changes to device data by opening a pull request directly against the public data repository, and have it validated, surfaced and attributed exactly like a change made through the website, so that both contribution paths are first-class and neither can bypass the other's rules.

This is the direct-PR channel of the first contribution iteration described in #74. It is the counterpart to the website channel (#185): same repository, same validation, same moderation, same visibility on the device page.

"Same validation" means: a hand-written PR must pass the same structural and content checks as a website-generated one, be labelled and moderated by the same bot rules, and show up as a pending edit on the affected device page. A contributor must not gain or lose anything by choosing one path over the other.

Scope

Repository conventions

• Documented layout: one file per trait, file naming, symlink conventions for relations (brand, categories, alias-of, duplicate-of), sharding scheme, and the schema of each trait file
• A CONTRIBUTING guide and PR template in the repository explaining the conventions, how to reference a source, and what to expect from validation and moderation
• Contributor guidelines in the wiki mirror the same content for non-Git readers

Validation (shared with the website channel)

• A validation step runs on every PR, regardless of origin: schema validation of changed files, allowed-values checks (e.g. category and brand must exist or be proposed in the same PR by the defined mechanism), symlink integrity, sharding path correctness, image constraints (type, size, licence acknowledgement in the PR description)
• Validation reports results as a PR check with actionable messages; a failing check blocks merge
• The website-generated PRs use the same validation; there is one implementation, not two

Visibility and attribution

• Any open PR that changes a device's trait appears as a pending edit on that device page, with the same display as website proposals
• Attribution uses the PR author's GitHub identity, matching how website proposals are attributed via Account 0.1
• Merged changes appear in the device page changelog the same way regardless of origin

Acceptance criteria

• A contributor can clone the repository, change a trait file following the documented conventions, open a PR, and see the validation check result within minutes
• The validation check is the same code path for website-generated and hand-written PRs; a change to validation rules affects both
• A PR failing validation cannot be merged by the bot; the check output tells the contributor what to fix
• A hand-written PR touching a device shows up as a pending edit on that device page, including a link to the PR
• A hand-written PR touching several traits is labelled for all of them and follows the strictest applicable merge rule
• Files or paths outside the conventions cause the PR to be flagged for human review rather than auto-merged
• CONTRIBUTING, PR template and wiki guidelines are published with the first release of the repository

Not in scope

• The website edit mode and its PR creation (Edit mode on the device page (website channel), reduced field set #185 and the PR creation feature)
• The moderation rules themselves and the voting mechanism (moderation bot feature); this feature consumes the labels and rules, it does not define them
• Proposing new traits or categories through PRs beyond what the first-iteration mechanism allows
• Bulk import tooling; large contributions are welcome via PR but no tooling is provided here
• A GitHub bot acting as proxy for contributors without a GitHub account
• Ingestion from external databases (Further enrichment from public databases #27)

Dependencies

• Data repository structure and tooling feature: repository layout, file schema, sharding
• Moderation bot feature: labels, per-trait merge rules, voting
• Website channel (Edit mode on the device page (website channel), reduced field set #185) and PR creation service, to confirm the shared validation contract
• Pending-edits display on the device page (changelog and pending-edits feature)
• Legal: licence terms for contributed content and image rights, to be referenced from CONTRIBUTING (Launch readiness for the public Device Database (public information, communication, Preview/Labs exit) #35)

Open questions