House opinions
This is how a house opinion gets into an ecosystem, and how it's marked. It lives here once. Each ecosystem's HOUSE-OPINIONS.md holds its Profiles table, its Inbox, and its Woven table. For what a reader sees, and how to choose a profile or keep one private, see House profiles.
House opinions are preferences from experience, not from a vetted source. Each belongs to a house profile, a named set of house opinions owned by a person or an organisation. They're always visibly marked, so a reader can tell community best practice from one owner's convention.
How this works
- The profile's owner adds an entry to the ecosystem's Inbox, naming the profile, in the entry format. A sentence or two is enough, as long as it gives the reasoning.
-
The
weave-house-opinionskill writes it in, beside the sourced text it changes. It never rewrites the sourced text.- In
opinions/: a block after the sourced recommendation it changes, which opens with/// house | <profile>and closes with///, each on its own line. - In
templates/: a region between two comment lines,house:<profile> beginandhouse:<profile> end, in the file's comment syntax, such as<!-- house:simon-mckenna begin -->in XML,# house:simon-mckenna beginin TOML, or// house:simon-mckenna beginin C# or Rust. - In
sources::house:<profile>, sorted like any other ID.
The inbox entry then moves to the ecosystem's Woven table, with a link.
- In
-
The marking is a fixed string. Every house opinion starts with exactly
**House:**, bold with the colon inside, sogrep -F '**House:**'finds it.just validate-sourcesfails a pull request unless ahouse:<profile>ID and that profile's blocks or regions appear together, and**House:**appears only inside one. - Keep both, and the profile decides which a reader sees. This is the canonical statement, and other files link here. The sourced text stays whole, and the house block sits beside it. A reader or agent with the profile sees both, and the house opinion wins where they conflict. Everyone else sees only the sourced text. Harvest, refresh, and audit runs never remove, weaken, or unmark a house block, and never cut sourced text because a house block disagrees with it.
- Other contributors propose opinions in a pull request, as the organisation's opinion pull request template describes. When a profile's owner accepts an experience-based opinion, they adopt it into their profile, and the Woven table's Provenance column credits the contributor and the pull request.
The site registers every profile in houses.toml, with the ecosystems that hold its opinions, and its build fails on a house opinion whose profile isn't registered there for that ecosystem. Before weaving a profile's first opinion in an ecosystem, add the ecosystem to the profile's ecosystems. A new profile needs the maintainer's approval, recorded there.
The house: prefix is reserved, as Admission criteria records. A profile skips the admission criteria because its authority is its owner's experience, which is why it's marked wherever it's used.
A woven block in opinions/ looks like this:
/// house | simon-mckenna
**House:** Treat warnings as errors on every machine, not only in CI. …
///