diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index cf0a209b..c5f5a696 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -9,8 +9,8 @@ body: Thanks for taking the time to report a bug. Please fill in the details below so the community can reproduce and evaluate it. - If you want to contribute a code fix, start with this report and wait - for a maintainer to confirm the scope before opening the pull request. + PRs are welcome. Prefer linking a fix to this report and include + test steps and results. See [CONTRIBUTING.md](https://github.com/srcfl/ftw/blob/master/CONTRIBUTING.md). FTW Community has no guaranteed response or resolution time. Do not include credentials, access tokens, private keys, or unredacted @@ -77,10 +77,3 @@ body: attributes: label: Anything else? description: Config snippets, screenshots, network topology, etc. - - type: checkboxes - id: text-first - attributes: - label: Contribution path - options: - - label: I understand that Sourceful handles implementation and external contributions use issues, not pull requests. - required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 7fb3d876..67f5c55d 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -10,9 +10,9 @@ body: a thread in [Discussions](../../discussions) first — issues are best for concrete, actionable proposals. - Sourceful develops FTW. External users submit issues with needs and - evidence; we do not accept external pull requests, including docs and - drivers. You do not need to design an API or write code to make a request. + PRs are welcome, preferably based on an issue. A broad idea can also + start as a short Markdown PR; a concrete fix should include test evidence. + You do not need to design an API or write code to make a request. - type: textarea id: problem attributes: @@ -64,10 +64,3 @@ body: attributes: label: Anything else? description: Hardware datasheets, protocol docs, screenshots, links. - - type: checkboxes - id: text-first - attributes: - label: Contribution path - options: - - label: I understand that Sourceful handles implementation and external contributions use issues, not pull requests. - required: true diff --git a/.github/check-no-planning-docs.sh b/.github/check-no-planning-docs.sh index cb6b1a83..3ec6cebd 100755 --- a/.github/check-no-planning-docs.sh +++ b/.github/check-no-planning-docs.sh @@ -1,14 +1,9 @@ #!/usr/bin/env bash # Fails when a change adds agent planning artefacts to the repository. # -# Plans, design specs and task breakdowns describe how work was going to be -# done. They are stale the moment the work lands, nobody reads them again, -# and they bury the docs that operators actually need. One PR carried 2,200 -# lines of them; the author's own point was that this would never have -# happened if the repo had simply said so. So the repo says so, here. -# -# Put the reasoning in the PR description instead. It gets read while the -# change is being reviewed, and then it is archived rather than maintained. +# Short Markdown proposals are welcome in the PR description or relevant +# maintained docs. This check rejects known scratch paths and dated agent +# work plans, not proposals as a contribution type. See CONTRIBUTING.md. set -euo pipefail BASE_SHA="${PLANNING_DOCS_BASE_SHA:-}" @@ -41,12 +36,12 @@ if [ -n "${offenders}" ]; then echo "This change adds agent planning documents:" >&2 echo "${offenders}" >&2 cat >&2 <<'MSG' -Plans, specs and design notes do not belong in the repository — see the -"Working alongside other people" section in AGENTS.md. Move the reasoning -into the pull request description and drop the files. +Task breakdowns and agent scratch notes do not belong in the repository. +Move work reasoning into the PR description and drop these files. -Documentation that explains architecture, a safety invariant, or a step an -operator has to take is welcome under docs/ and is not what this checks for. +Short Markdown proposals are welcome in the PR description or relevant +maintained docs. Mark proposed behaviour as proposed. Architecture, safety +and operator docs remain welcome. See CONTRIBUTING.md and AGENTS.md. MSG exit 1 fi diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index add2211d..aa48a716 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,7 +1,9 @@ ## Problem and result @@ -14,7 +16,9 @@ See CONTRIBUTING.md. Acceptance of an issue does not invite an external PR. ## Verification - + ## Checklist diff --git a/AGENTS.md b/AGENTS.md index d1d51030..d6846fb7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,8 +7,10 @@ requirements and [docs/roadmap.md](docs/roadmap.md) for acceptance evidence. These are direction, not claims that all planned behaviour has shipped. Fredrik owns FTW's direction. Sourceful develops and maintains it. External -users submit issues; we do not accept external pull requests, including docs -and drivers. See [CONTRIBUTING.md](CONTRIBUTING.md). +PRs are welcome, preferably based on issues. Broad proposals may start as +short Markdown PRs; concrete fixes need relevant test evidence. Work is +agentic first: make the problem, scope and results clear enough for people +and agents to assess and continue. See [CONTRIBUTING.md](CONTRIBUTING.md). ## Product rules @@ -129,10 +131,12 @@ landed on somebody else's finished work. enough. Keep VISION.md and the roadmap current as the maintained product direction. -Task plans, design drafts, breakdowns and agent scratch notes stay out of the -repository; [`.github/check-no-planning-docs.sh`](.github/check-no-planning-docs.sh) enforces -this. Commit the change, its tests and a changeset; put the reasoning in the -PR description, where it is read during review and then archived. +Short Markdown proposals may update the relevant maintained docs or use the +PR description. Mark proposed behaviour as proposed until it ships. Keep task +breakdowns, run logs and agent scratch notes out of the repository; +[`.github/check-no-planning-docs.sh`](.github/check-no-planning-docs.sh) checks known +scratch paths. Code PRs include the change, relevant tests and a changeset +when required. Put work reasoning in the PR description. ## Build and test diff --git a/APPROVAL_POLICY.md b/APPROVAL_POLICY.md index 2823725c..fe1e30d3 100644 --- a/APPROVAL_POLICY.md +++ b/APPROVAL_POLICY.md @@ -23,4 +23,6 @@ that check. Preserve the owner's release and beta-review rules in AGENTS.md. This policy grants no extra authority to approve, merge, release or operate a site. It also adds no confirmation requirement when the owner has already -authorized the action. External users submit issues; Sourceful maintains PRs. +authorized the action. External PRs are welcome under CONTRIBUTING.md; +Sourceful reviews and maintains changes. Submission grants no merge or +release authority, whether a person or an agent wrote the change. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e05374e..4b527eed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,41 @@ # Contributing to FTW -Sourceful develops FTW and Fredrik owns its direction. External users help -through [issues](https://github.com/srcfl/ftw/issues): report bugs, describe -needs and share evidence. We do not accept external pull requests, including -documentation, driver and website changes. Acceptance of an issue does not -invite an external implementation PR. - -The [product vision](VISION.md) guides the work Sourceful selects. Users may -still run, inspect and adapt FTW under its existing license. This policy does -not change the license or past contributions. The development and sign-off -instructions below apply to Sourceful-maintained changes and local work. +Sourceful develops and maintains FTW; Fredrik owns its direction. External +PRs are welcome, including code, drivers, documentation and website changes. +Prefer an [issue](https://github.com/srcfl/ftw/issues) that states the need and +evidence, and link it from the PR. Small fixes do not need a separate issue. +The [product vision](VISION.md) guides scope and priority. + +For a broad product or architecture idea, a short Markdown PR is a useful +start. Explain the problem, proposed result and how we could test it in the +PR description or relevant maintained docs. Mark proposals as proposed; +keep agent scratch notes and task breakdowns out of the repository. Concrete +fixes can include code and tests. No proposal promises a delivery date. + +## Agentic first + +People and agents should be able to assess and continue the work from its +record. State the problem, scope, relevant issue, test steps and results. +Use focused changes and reproducible evidence. The submitter checks agent +output and remains responsible for the contribution and its sign-off. + +Test evidence should fit the change. For device behaviour, include hardware +model, firmware, test steps and observed results before merge. State missing +hardware tests and keep the PR as a proposal or draft until they are done. +Simulator tests help catch bugs but do not prove physical support. Docs do +not need hardware tests; UI changes need a browser review. Driver control +keeps its separate safety and hardware acceptance gates. + +This policy changes no license, past attribution or release authority. ## Website The public website () lives in its own repository, [`srcfl/ftw-web`](https://github.com/srcfl/ftw-web). Landing-page -copy, install instructions and other site content live there. Report website -changes in [its issue tracker](https://github.com/srcfl/ftw-web/issues). +copy, install instructions and other site content live there. Use +[its issue tracker](https://github.com/srcfl/ftw-web/issues) and PRs for website +changes. Shared Lua drivers belong in +[`srcfl/device-drivers`](https://github.com/srcfl/device-drivers). ## License of contributions @@ -89,11 +108,11 @@ involved. Add relevant logs, screenshots or protocol documents when available. Do not post credentials or private site data. You do not need to design an API or write a patch to report a problem. -Sourceful decides scope and priority and links implementation PRs to the issue. -External PRs are not the intake path; maintainers may close them and direct the -author to issues. General questions can still use Discussions or Discord. +Fredrik sets direction and priority; Sourceful reviews and maintains changes. +Link related issues and PRs so the evidence stays easy to follow. General +questions can use Discussions or Discord. -## Sourceful pull requests +## Pull requests - State the household need, selected scope and relevant issue or owner request. - Keep the change focused and coordinate overlap with open work. diff --git a/README.md b/README.md index cf9f1747..1b303993 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,9 @@ while keeping expert controls and Lua drivers available. [docs/roadmap.md](docs/roadmap.md) lists the outcomes and proof needed. These include goals that have not shipped; the capability list below is separate. -Sourceful Energy maintains FTW Community under Apache-2.0. External users -report bugs, needs and evidence through [issues](https://github.com/srcfl/ftw/issues). -We do not accept external pull requests, including documentation and drivers. +Sourceful Energy maintains FTW Community under Apache-2.0. Contributions are +welcome, preferably starting with [issues](https://github.com/srcfl/ftw/issues). +Share a short Markdown proposal or a focused fix with relevant test evidence. See [CONTRIBUTING.md](CONTRIBUTING.md). Community help is best effort; [SUPPORT.md](SUPPORT.md) describes separate commercial services. diff --git a/SUPPORT.md b/SUPPORT.md index 1bb3f6f5..bdecaa77 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -17,9 +17,9 @@ Use the public community channels for help: searchable questions, ideas, and open-ended technical conversation; - report reproducible bugs and request features in [GitHub Issues](https://github.com/srcfl/ftw/issues); -- describe proposed fixes, driver needs, test evidence and documentation - corrections in issues. Sourceful implements selected changes; external pull - requests are not accepted. See [CONTRIBUTING.md](CONTRIBUTING.md). +- share proposed fixes, driver needs and test evidence in issues. PRs are + welcome, including short Markdown proposals and documentation fixes. + See [CONTRIBUTING.md](CONTRIBUTING.md). Maintainers and community members may help on a best-effort basis. A question may receive no response, and a fix may not arrive on a particular schedule. diff --git a/VISION.md b/VISION.md index d7c4fe66..eb93aa7c 100644 --- a/VISION.md +++ b/VISION.md @@ -205,11 +205,18 @@ Agents work within the scope and authority given to them. Reviews should provide an independent assessment and evidence; file-based reviewer lists do not define product ownership. -External users contribute through issues: bugs, needs, hardware evidence and -suggestions. FTW does not accept external pull requests, including drivers, -documentation and website changes. Sourceful maintains implementation PRs. -Users may still inspect, run and adapt the software under its existing license. -This contribution policy changes no license or copyright attribution. +External contributions are welcome, including code, drivers, documentation +and website PRs. Prefer an issue that states the need and evidence. A broad +product or architecture proposal can start as a short Markdown PR; a concrete +fix can include code and tests. Hardware changes need relevant hardware +evidence before we claim working support. + +Development is agentic first. Make problems, scope, test steps and results +clear enough for people and agents to assess and continue the work. The +submitter checks the result; agent output alone is not test evidence. +Sourceful reviews and maintains changes; Fredrik sets direction and priority. +An accepted issue or proposal does not promise implementation or delivery. +This policy changes no license, copyright attribution or release authority. The operating rules live in [AGENTS.md](AGENTS.md), review routing in [APPROVAL_POLICY.md](APPROVAL_POLICY.md), and contribution details in diff --git a/docs/roadmap.md b/docs/roadmap.md index 8c1d966d..d56f937a 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -196,8 +196,12 @@ telemetry-only driver or require every house to supply a thermal model. ## How work enters the roadmap -External users submit issues, not PRs. Sourceful implements selected work. -Acceptance of an issue does not invite an external implementation PR. +Contributions are welcome, preferably based on an issue. Broad ideas may +start as short Markdown PRs; concrete fixes can include code and relevant +test evidence. Hardware claims need hardware results. Work is agentic first: +make the problem, scope and results clear enough for people and agents to +assess and continue. Fredrik sets priority; Sourceful reviews and maintains +changes. An accepted issue or proposal does not promise delivery. For each selected change, state the household need, the behaviour to change, the existing work it touches and the evidence that will establish completion.