From bfceb9d187bdc842d2a3346276c7125b275a95d7 Mon Sep 17 00:00:00 2001 From: Fredrik Ahlgren Date: Sat, 12 Sep 2026 12:54:48 +0200 Subject: [PATCH] docs: welcome issue-led contributions and Markdown proposals Signed-off-by: Fredrik Ahlgren --- .github/ISSUE_TEMPLATE/driver_request.yml | 5 ++-- .github/PULL_REQUEST_TEMPLATE.md | 8 +++--- AGENTS.md | 6 +++-- CONTRIBUTING.md | 30 ++++++++++++++--------- README.md | 11 +++++---- docs/WRITING-A-DRIVER.md | 6 ++--- 6 files changed, 40 insertions(+), 26 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/driver_request.yml b/.github/ISSUE_TEMPLATE/driver_request.yml index 4c22b8a..569068a 100644 --- a/.github/ISSUE_TEMPLATE/driver_request.yml +++ b/.github/ISSUE_TEMPLATE/driver_request.yml @@ -6,8 +6,9 @@ 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. + Share device needs and evidence here. PRs are welcome, preferably linked + to an issue: a short Markdown proposal or a focused fix with test results. + Hardware claims need hardware evidence. See CONTRIBUTING.md. - type: input id: device attributes: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 2965903..cf391ed 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,9 +1,11 @@ - + ## Summary - + ## Driver evidence diff --git a/AGENTS.md b/AGENTS.md index 60a0e33..587f53b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,8 +9,10 @@ for other products or support levels, but it does not own a second source tree. 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 +External PRs are welcome, preferably based on issues with needs and evidence. +Work is agentic first: state the problem, scope, test steps and actual results. +Short Markdown proposals are welcome; hardware changes keep the acceptance +gates below. 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e49f778..3f889cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,24 @@ # Contributing device drivers -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). +Sourceful maintains this repository. External PRs are welcome, preferably +based on [issues](https://github.com/srcfl/device-drivers/issues) with device +needs, bugs, protocol sources and hardware evidence. Small fixes need no +separate issue. Broad ideas may start as short Markdown PRs in the PR +description or relevant maintained docs; mark proposed behaviour as proposed. +Keep agent scratch notes and task breakdowns out of the repository. + +Work is agentic first: state the problem, scope, reproducible test steps and +actual results so people and agents can assess and continue it. Check agent +output before submitting it. For device behaviour, include model, firmware +and hardware results before merge. State missing hardware tests and keep the +PR as a proposal or draft until they are done. Simulators do not prove +physical support. Docs need no hardware tests. Control keeps its separate +acceptance gates below. + +Keep PRs focused on one driver or contract change. Local adaptation and PRs +grant no release, signing or activation authority. Fredrik owns FTW's +direction in [the shared vision](https://github.com/srcfl/ftw/blob/master/VISION.md); +Sourceful reviews and maintains changes under the existing license. ## Legal sign-off diff --git a/README.md b/README.md index d9405ab..9aceaaf 100644 --- a/README.md +++ b/README.md @@ -26,12 +26,13 @@ hardware. ## 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. +Sourceful maintains the drivers and releases. External PRs are welcome, +preferably based on [issues](https://github.com/srcfl/device-drivers/issues) +with hardware needs, bugs and test evidence. Share a short Markdown proposal +or a focused fix; hardware claims need hardware results. [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. +The instructions below serve contributions and local adaptation. Start from **[`blueprint/BLUEPRINT.lua`](blueprint/BLUEPRINT.lua)**. It is a complete, working driver for an imaginary inverter, written so that every rule @@ -51,7 +52,7 @@ fabricated zero is worse than a missing field, and why arithmetic never belongs in the host API. For an issue, include the device model, protocol source and any observations -you can safely share. Sourceful implementation PRs use the template and include +you can safely share. Implementation PRs use the template and include sign checks and test evidence without credentials or private site data. New drivers start with telemetry only. Control support needs a later, diff --git a/docs/WRITING-A-DRIVER.md b/docs/WRITING-A-DRIVER.md index 519a699..95d05fc 100644 --- a/docs/WRITING-A-DRIVER.md +++ b/docs/WRITING-A-DRIVER.md @@ -1,8 +1,8 @@ # 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. +This guide serves contributions and local Lua adaptation. PRs are welcome, +preferably based on [issues](https://github.com/srcfl/device-drivers/issues) +with needs and evidence. Hardware claims need relevant hardware results. See [CONTRIBUTING.md](../CONTRIBUTING.md). Start here: **[`blueprint/BLUEPRINT.lua`](../blueprint/BLUEPRINT.lua)**.