diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ca3291e..ec134c37 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,66 +1,266 @@ -## Contributing +# Contributing -Thank you for contributing to this repository. +Thank you for contributing to WFGY. -This project is maintained with a focus on inspectable work, verifiable references, and clear scope boundaries. -To reduce ambiguity and avoid overstated claims, contributions are routed into a small number of reviewable lanes. +WFGY is maintained as a public ecosystem for reasoning, debugging, evaluation, and structural AI system analysis. -At the current stage, there are two primary contribution lanes. Most accepted PRs are expected to fall into one of them. +This repository values: -### Priority lane A: Tension Universe MVP Experiments +* inspectable work +* verifiable references +* narrow scope +* explicit assumptions +* conservative claims +* readable structure -The highest priority contribution path is expanding and improving the Tension Universe MVP experiment layer. +The goal is not to sound bigger than the evidence supports. +The goal is to make useful work easier to inspect, verify, improve, and extend. -This lane focuses on adding or improving MVP experiment pages under the `TensionUniverse/Experiments/` collection. -An MVP experiment here does not mean a solved claim, a final proof, or a complete benchmark. It means a narrow, inspectable page with explicit assumptions and a reproducible or at least reviewable protocol. +## A simple rule for contributing + +If any part of this repository falls below a clear scientific standard, it is worth improving. + +That includes cases where: + +* a statement is too vague +* a claim is too strong +* a boundary is unclear +* a link is broken +* a section is hard to navigate +* a label is misleading +* a sentence is imprecise +* a word choice weakens rigor + +In this repository, even a one-word fix can be a meaningful contribution if it improves clarity, accuracy, or auditability. + +Small contributions are welcome. +Precision is part of the work. + +--- + +## What kinds of contributions are welcome + +At the current stage, contributions usually fall into a small number of reviewable lanes. + +### Priority lane A: Tension Universe MVP experiments + +One priority contribution path is improving the Tension Universe MVP experiment layer. + +This lane focuses on adding or refining MVP experiment pages under the `TensionUniverse/Experiments/` collection. + +An MVP experiment here does not mean a solved claim, a final proof, or a complete benchmark. +It means a narrow, inspectable artifact with explicit assumptions and a reproducible or at least reviewable protocol. Typical contributions in this lane include: -- adding a new MVP experiment page for an open Tension Universe problem -- improving an existing MVP experiment page with clearer structure, tighter scope, or better protocols -- attaching small supporting artifacts that belong to the MVP page, such as notebooks, Colab links, screenshots, or structured notes +* adding a new MVP experiment page for an open Tension Universe problem +* improving an existing MVP experiment page with tighter scope or clearer structure +* attaching supporting artifacts that belong to the MVP page, such as notebooks, Colab links, screenshots, or structured notes Start here: -- [Tension Universe MVP contribution guide](https://github.com/onestardao/WFGY/blob/main/TensionUniverse/CONTRIBUTING.md) +* [Tension Universe MVP contribution guide](./TensionUniverse/CONTRIBUTING.md) -### Priority lane B: Recognition Map updates +--- -The second priority lane is maintaining a verified, public recognition record of where WFGY has been cited, integrated, adapted, or discussed across the ecosystem. +### Priority lane B: public proof and recognition updates -If you find a public repository, benchmark, article, doc page, course page, or discussion that includes WFGY, you are welcome to help keep this list accurate. +A second priority contribution path is maintaining an accurate, public record of where WFGY has been cited, integrated, adapted, referenced, or discussed. -You can contribute by: +If you find a public repository, benchmark, article, survey, doc page, course page, or discussion that includes WFGY, you are welcome to help keep the evidence layer accurate. -- adding a missing entry -- updating an outdated description -- attaching a better proof link -- correcting categorization -- submitting a PR with a new citation or integration +Typical contributions in this lane include: -Forks and PRs are welcome. If your project includes WFGY in any public form, feel free to add it to this recognition list with a short description and a verifiable link. +* adding a missing public reference +* improving a weak or outdated proof link +* correcting categorization +* clarifying how a public mention should be read conservatively +* suggesting whether a case belongs in Recognition Map, Adopters, Case Evidence, or Evidence Timeline -Recognition Map: +Useful pages in this lane include: -- [WFGY Recognition Map](https://github.com/onestardao/WFGY/blob/main/recognition/README.md) +* [Recognition Map](./recognition/README.md) +* [Adopters](./ADOPTERS.md) +* [Case Evidence](./CASE_EVIDENCE.md) +* [Evidence Timeline](./EVIDENCE_TIMELINE.md) -### Other contributions are also welcome +--- -In addition to the two priority lanes above, other forms of contributions are welcome, for example: +### Priority lane C: documentation, navigation, and wording precision -- wording and clarity improvements -- typo fixes -- broken link fixes -- navigation and formatting improvements -- small documentation refinements that reduce confusion for readers and automated tools +A third priority contribution path is improving readability, structure, routing, and scientific precision across the repo. -If you are unsure which lane your contribution belongs to, open a short issue first and describe the intended change and the target file. +This lane is especially important because WFGY is no longer a single page. +It is a multi-layer public system, and clear navigation matters. -### Review expectations +Typical contributions in this lane include: + +* wording and clarity improvements +* typo fixes +* broken link fixes +* section-title improvements +* page-routing fixes +* structural improvements that help new readers understand where to start +* edits that reduce overstatement or strengthen scope boundaries + +This lane also includes small wording corrections that improve scientific rigor. + +If a phrase is too broad, too casual, too inflated, or too ambiguous, it is reasonable to propose a fix. + +--- + +## Small fixes are real contributions + +Not every useful contribution is a feature, experiment, or major page. + +These also count: + +* fixing one misleading sentence +* tightening one weak paragraph +* replacing one broken or low-quality link +* correcting one category label +* improving one reading path +* removing one overclaim +* making one page easier to audit + +This repository treats clarity, restraint, and structure as real work. + +--- + +## How to contribute + +### 1. Use the issue templates when possible + +This repository provides issue templates for several common contribution paths, including: + +* recognition updates +* documentation and navigation improvements +* bug reports +* feature requests +* questions or help + +Use the closest matching template when possible. + +If none of the templates fit, a blank issue is still acceptable. +Just explain clearly what you want to change and why the existing templates do not fit. + +### 2. Open a focused issue first when the change is non-trivial + +If your change affects structure, categorization, routing, collaboration language, proof interpretation, or multiple pages, open a short issue first. + +That makes review faster and reduces unnecessary rework. + +### 3. Submit a narrow PR + +Please keep PRs focused. + +A good PR in this repository usually does one of the following: + +* improves one page or one group of closely related pages +* adds one new evidence item with proof +* fixes one navigation problem +* clarifies one structural boundary +* improves one contribution or workflow surface + +Narrow PRs are easier to review and easier to trust. + +--- + +## Review expectations To keep contributions aligned with scientific practice and public auditability: -- keep scope narrow and assumptions explicit -- avoid exaggerated claims, especially for early MVP work -- prefer verifiable links and reproducible steps over broad statements -- for recognition entries, include a public proof link whenever possible +* keep scope narrow +* make assumptions explicit +* prefer verifiable links over broad statements +* avoid exaggerated claims, especially for early MVP work +* separate observation from interpretation +* state non-claims when needed +* do not present mention-level evidence as adoption +* do not present support as collaboration +* do not present collaboration pages as proof of deployment + +For public proof updates, include a stable public source whenever possible. + +For docs and wording changes, optimize for clarity, precision, and lower reader confusion. + +--- + +## Evidence standard + +When contributing to public proof pages, use disciplined reading. + +Examples: + +* a merged documentation PR is not automatically paid adoption +* a citation is not the same as integration +* a mention is not the same as production deployment +* a packaging milestone is not the same as external validation + +If a case is useful but weak, it may still belong in the Recognition Map. +It does not automatically belong in Adopters or Case Evidence. + +Conservative reading is a feature, not a limitation. + +--- + +## PR expectations + +A pull request should explain: + +* what changed +* where it changed +* why it matters +* what it does not prove, if relevant + +If the PR touches public proof, recognition, adoption, collaboration, or ecosystem interpretation, keep claims especially disciplined. + +If the PR affects templates, docs, or routing, make sure links and destination pages are correct. + +--- + +## What not to do + +Please avoid the following: + +* broad promotional rewrites +* inflated claims without proof +* vague benchmark language without inspectable references +* mixing support language with collaboration language +* mixing mention-level evidence with stronger adoption language +* large multi-topic PRs without prior discussion +* speculative claims presented as settled facts + +This repository prefers inspectable progress over dramatic wording. + +--- + +## If you want collaboration instead of contribution + +If your goal is not a public contribution but a structured pilot, audit, or research-facing collaboration, use the collaboration path instead of the contribution path. + +Start here: + +* [Work with WFGY](./WORK_WITH_WFGY.md) +* [Pilot Offer One-Pager](./PILOT_OFFER_ONE_PAGER.md) +* [Sample Deliverable](./SAMPLE_DELIVERABLE.md) + +--- + +## If you want to support the project + +If you want to support continued development financially or through other forms of public support, use the support path: + +* [Support WFGY](./SUPPORT.md) + +Support and contribution are both meaningful, but they are not the same thing. + +--- + +## Final note + +This repository is maintained with a strong preference for scientific restraint. + +If you can help make WFGY more precise, more navigable, more verifiable, or easier to inspect, your contribution is welcome. + +That remains true whether you improve a major page, a public proof entry, a workflow template, or a single sentence.