From 409a0235187bc5b08b4ef3b16dbc0b611572a856 Mon Sep 17 00:00:00 2001 From: Fredrik Ahlgren Date: Sat, 12 Sep 2026 10:48:59 +0200 Subject: [PATCH] docs: align FTW product vision and ownership Signed-off-by: Fredrik Ahlgren --- .github/ISSUE_TEMPLATE/driver_request.yml | 9 +++++++-- .github/PULL_REQUEST_TEMPLATE.md | 3 +++ AGENTS.md | 16 ++++++++++++++++ CONTRIBUTING.md | 15 ++++++++++++--- README.md | 17 ++++++++++++----- docs/WRITING-A-DRIVER.md | 7 ++++++- 6 files changed, 56 insertions(+), 11 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/driver_request.yml b/.github/ISSUE_TEMPLATE/driver_request.yml index afb4adc..4c22b8a 100644 --- a/.github/ISSUE_TEMPLATE/driver_request.yml +++ b/.github/ISSUE_TEMPLATE/driver_request.yml @@ -1,8 +1,13 @@ name: Driver request -description: Request support for a device or propose a driver contribution +description: Request device support or share hardware evidence title: "[driver] " labels: ["driver"] body: + - type: markdown + attributes: + value: | + Sourceful develops the drivers. External users submit issues with needs + and evidence; we do not accept external pull requests, including docs. - type: input id: device attributes: @@ -30,4 +35,4 @@ body: attributes: label: Contribution options: - - label: I can help write or test this driver. + - label: I can provide device documentation or help test on hardware. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 89c3f7e..2965903 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,3 +1,6 @@ + + ## Summary diff --git a/AGENTS.md b/AGENTS.md index 355667f..60a0e33 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,22 @@ drivers and the main driver source for FTW. It publishes FTW's signed driver channel from reviewed commits. Device Support may later consume a locked commit for other products or support levels, but it does not own a second source tree. +## FTW product direction + +Read [FTW's vision](https://github.com/srcfl/ftw/blob/master/VISION.md) for the household +experience these drivers support. Sourceful maintains this shared repository. +External users submit issues with needs and evidence, not implementation PRs. +See [CONTRIBUTING.md](CONTRIBUTING.md). Local Lua customization remains useful +and does not grant signed-channel activation or release rights. + +Support mixed makes and generations with explicit model/firmware evidence. +Report identity, reliable measurements, known limits and structured command +results so Core can distinguish read support from control support. A catalog +entry or a simulated response does not establish working physical control. +Heat telemetry helps planning first; active tank or hot-water control requires +its separate safety and hardware evidence. Keep the existing host contracts +and control acceptance gates below. + ## Boundaries - Keep API, admin, database and deployment code out of this repo. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 090479d..e49f778 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,16 @@ # Contributing device drivers -Thank you for helping add hardware support. Keep each pull request focused on -one driver or one contract change. +Sourceful maintains this repository. External users contribute through +[issues](https://github.com/srcfl/device-drivers/issues): device needs, bugs, +protocol sources and hardware evidence. We do not accept external pull +requests, including documentation. Acceptance of an issue does not invite an +external implementation PR. + +Users may adapt Lua drivers locally under the existing license. Local changes +do not grant release, signing or activation authority. The development steps +below apply to Sourceful-maintained PRs and local adaptation. Keep Sourceful +PRs focused on one driver or one contract change. FTW direction lives in +[the shared vision](https://github.com/srcfl/ftw/blob/master/VISION.md). ## Legal sign-off @@ -146,7 +155,7 @@ State: Do not post credentials, full configuration, serial numbers, private addresses or energy history from a real site. -New contributions use the `community` tier. That tier states the current test +New drivers use the `community` evidence tier. That tier states the current test and support evidence; it does not mean the public repo is unofficial or unmaintained. A maintainer may promote a driver only after the stated review and hardware checks. Control support always uses a separate change and cannot diff --git a/README.md b/README.md index a7ddc8b..d9405ab 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,14 @@ Being listed is not an install claim. The page states the same evidence the repository does, including how few drivers have been confirmed against physical hardware. -## Contribute a driver +## Report a need or adapt a driver + +Sourceful maintains implementation and release PRs. External users submit +[issues](https://github.com/srcfl/device-drivers/issues) with hardware needs, +bugs and test evidence; we do not accept external PRs, including docs. +[FTW's product vision](https://github.com/srcfl/ftw/blob/master/VISION.md) +sets the FTW goals. The existing license still permits local adaptation. +The instructions below serve local work and Sourceful development. Start from **[`blueprint/BLUEPRINT.lua`](blueprint/BLUEPRINT.lua)**. It is a complete, working driver for an imaginary inverter, written so that every rule @@ -43,11 +50,11 @@ behind each rule — why a failed read can take a whole site offline, why a fabricated zero is worse than a missing field, and why arithmetic never belongs in the host API. -Then open a pull request using the template. Include the tested device models, -the protocol source, sign checks against vendor data and a test fixture when -one can be shared without credentials or site data. +For an issue, include the device model, protocol source and any observations +you can safely share. Sourceful implementation PRs use the template and include +sign checks and test evidence without credentials or private site data. -New community drivers start with telemetry only. Control support needs a later, +New drivers start with telemetry only. Control support needs a later, separate review with a safe default mode, a bounded command lease, structured results and supervised hardware-in-the-loop evidence. diff --git a/docs/WRITING-A-DRIVER.md b/docs/WRITING-A-DRIVER.md index d53770e..519a699 100644 --- a/docs/WRITING-A-DRIVER.md +++ b/docs/WRITING-A-DRIVER.md @@ -1,5 +1,10 @@ # Writing a driver +This guide serves local Lua adaptation and Sourceful development. External +users submit [issues](https://github.com/srcfl/device-drivers/issues) with +needs and evidence; the project does not accept external pull requests. +See [CONTRIBUTING.md](../CONTRIBUTING.md). + Start here: **[`blueprint/BLUEPRINT.lua`](../blueprint/BLUEPRINT.lua)**. It is a complete, working driver for an imaginary inverter. Every rule in this @@ -95,7 +100,7 @@ Wrap the driver's own typed helpers — `read_i16`, `read_u32_be` and the like around `probe_read` rather than giving each its own `pcall`. That fixes every call site at once and leaves one place to reason about. -### Check your driver before you open the pull request +### Check local changes and Sourceful pull requests ```bash make absent-register-report ID=example