diff --git a/STANDARDS.md b/STANDARDS.md index fdbcfc4..e580a2e 100644 --- a/STANDARDS.md +++ b/STANDARDS.md @@ -192,18 +192,18 @@ first impression, not last word. Treat it accordingly. ASCII diagram of the data flow / architecture is a satisfying substitute. A wall of text is not. - **One quick example**, 5–15 lines, that a reader can run right - after install. Don't catalogue every variant. *(Not applicable to - research lines — see - [`project-type/RESEARCH-LINE.md`](project-type/RESEARCH-LINE.md) §2; - they carry `## Run it` plus a captured trace instead.)* + after install. Don't catalogue every variant. *(Suspended for repos + under [`overlay/PUBLISHED-VERDICT.md`](overlay/PUBLISHED-VERDICT.md) + §2 — they carry `## Run it` plus a captured trace instead.)* - **Capability bullets**, not API tables. README lists *what you can do*; `docs/API.md` lists *every public symbol*. - **Deflect to `docs/`** for depth — API reference, recipes, migration, architecture. Each link gets a one-line description. - **Family table** (sibling Codechu packages) so visitors find the - ecosystem. *(Not applicable to research lines — they are not - published to a registry; name the sibling relationship in a sentence - and link the repository.)* + ecosystem. *(Suspended under + [`overlay/PUBLISHED-VERDICT.md`](overlay/PUBLISHED-VERDICT.md) §2 — + the sibling is often not published at all; name the relationship in a + sentence and link the repository.)* - **License + credits** at the bottom. **Explicit prohibitions in README:** @@ -232,9 +232,9 @@ assets/ By v0.1.0 the README must not be text-only. Either inline a Mermaid block or reference an `assets/` file. The per-project-type docs ([`project-type/LIBRARY.md`](project-type/LIBRARY.md), -[`APPLICATION.md`](project-type/APPLICATION.md), -[`RESEARCH-LINE.md`](project-type/RESEARCH-LINE.md)) restate this rule -with type-specific skeletons. +[`TOOL.md`](project-type/TOOL.md), +[`APPLICATION.md`](project-type/APPLICATION.md)) restate this rule with +type-specific skeletons. **Rendering rules (measured, not assumed).** Each of these was found by rendering a README through `gh api /markdown` and looking at the page; @@ -253,9 +253,17 @@ none of them are visible while reading the markdown source. - **Every badge is a link.** A badge pointing nowhere is decoration wearing the costume of a signal. *Incident: three of four badges in one README were dead images.* -- **Command lines must fit the column** — under ~60 characters. GitHub - does not wrap inside a code fence; it clips. *Incident: the first - command a reader saw rendered as `# 80 tests, no networ`.* +- **A code fence clips; it does not wrap.** A line past the column edge + is cut silently, and the reader never learns what was there. + *Measured by rendering a ruler of increasing line lengths — pandoc + plus github-markdown-css, screenshotted in headless Chrome at a fixed + window width: the desktop column fits ~100 characters, a 390 px phone + ~42. An earlier revision of this rule said "under ~60 characters", on + the strength of a single 58-character line reported as clipped. That + observation does not reproduce at any width our readers use, and ~60 + was measured against nothing: it clips on a phone and is pointless on + a desktop. Budget the column your readers are actually on, and + measure it before quoting a number.* - **Fence every typable thing with a language tag.** An indented four-space block renders as a bare `
` with no highlighting; reserve indentation for non-typable ASCII. @@ -458,10 +466,12 @@ layers extend it: | Layer | Path | Scope | |---|---|---| -| Project type | [`project-type/`](project-type/) | Library, application, or research line; any language | +| Project type | [`project-type/`](project-type/) | Library, tool, or application; any language | | Language | [`lang//`](lang/) | Per-language extensions (Python today) | +| Overlay | [`overlay/`](overlay/) | Disciplines any type may adopt; they add rather than narrow | -Read in order: STANDARDS → project-type → lang. +Read in order: STANDARDS → project-type → lang, then any overlay the +repository adopts. ## 14. Active repositories diff --git a/STANDARDS.tr.md b/STANDARDS.tr.md index 13e180d..aeb1db5 100644 --- a/STANDARDS.tr.md +++ b/STANDARDS.tr.md @@ -195,17 +195,19 @@ gördüğü ilk şey — son söz değil, ilk izlenim. Buna göre davran. ASCII diyagram doyurucu bir alternatiftir. Düz metin duvarı kabul edilemez. - **Tek hızlı örnek**, 5–15 satır, kurulumdan hemen sonra - çalıştırılabilir olsun. Her varyantı sıralama. *(Araştırma hatları - için geçersiz — - [`project-type/RESEARCH-LINE.md`](project-type/RESEARCH-LINE.md) §2; - onun yerine `## Run it` + gerçek yakalanmış iz gelir.)* + çalıştırılabilir olsun. Her varyantı sıralama. *( + [`overlay/PUBLISHED-VERDICT.md`](overlay/PUBLISHED-VERDICT.md) §2 + altındaki depolar için ASKIDA — onun yerine `## Run it` + gerçek + yakalanmış iz gelir.)* - **Yetenek bullet'ları**, API tabloları değil. README *yapabildiklerini* listeler; `docs/API.md` *her public sembolü* listeler. - **`docs/`'a yönlendir** — API referansı, recipe'ler, migration, mimari için. Her link tek satır açıklama ile gelsin. - **Family tablosu** (kardeş Codechu paketleri) — ziyaretçi - ekosistemi bulabilsin. *(Araştırma hatları için geçersiz — registry'ye - yayımlanmıyorlar; kardeşlik tek cümleyle söylenir ve repo linklenir.)* + ekosistemi bulabilsin. *( + [`overlay/PUBLISHED-VERDICT.md`](overlay/PUBLISHED-VERDICT.md) §2 + altında ASKIDA — kardeş çoğu zaman hiç yayımlanmamıştır; ilişki tek + cümleyle söylenir ve repo linklenir.)* - **Lisans + credits** en altta. **README'de açık yasaklar:** @@ -234,8 +236,8 @@ assets/ v0.1.0 itibarıyla README sadece-metin olamaz. Ya inline bir Mermaid bloğu ya da `assets/` referansı şart. Proje-tipi rehberleri ([`project-type/LIBRARY.md`](project-type/LIBRARY.md), -[`APPLICATION.md`](project-type/APPLICATION.md), -[`RESEARCH-LINE.md`](project-type/RESEARCH-LINE.md)) bu kuralı +[`TOOL.md`](project-type/TOOL.md), +[`APPLICATION.md`](project-type/APPLICATION.md)) bu kuralı tip-spesifik iskeletlerle yeniden ifade eder. **Render kuralları (ölçüldü, varsayılmadı).** Aşağıdakilerin hepsi bir @@ -254,9 +256,16 @@ hiçbiri markdown kaynağı okunurken görünmüyor. - **Her badge link olmalı.** Hiçbir yere gitmeyen badge, sinyal kostümü giymiş süstür. *Vaka: bir README'de dört badge'in üçü ölü görseldi.* -- **Komut satırları sütuna sığmalı** — ~60 karakterin altında. GitHub - code fence içinde sarmaz, keser. *Vaka: okurun gördüğü ilk komut - `# 80 tests, no networ` olarak render oldu.* +- **Code fence keser, sarmaz.** Sütun kenarını geçen satır sessizce + kesilir ve okur orada ne yazdığını hiç öğrenemez. *Artan uzunlukta bir + cetvel render edilerek ölçüldü — pandoc + github-markdown-css, sabit + pencere genişliğinde headless Chrome: masaüstü sütunu ~100 karakter + alıyor, 390 px telefon ~42. Bu kuralın önceki hâli "~60 karakterin + altında" diyordu; dayanağı, kesildiği bildirilen tek bir 58 karakterlik + satırdı. O gözlem okurlarımızın kullandığı hiçbir genişlikte + tekrarlanmıyor ve ~60 hiçbir şeye karşı ölçülmemişti: telefonda keser, + masaüstünde gereksizdir. Okurlarınızın fiilen bulunduğu sütunu + bütçeleyin, ve bir sayı yazmadan önce ölçün.* - **Yazılabilir her şey dil etiketli fence içinde.** Dört boşlukla girintilenmiş blok çıplak ` ` olarak render olur, highlight almaz; girintiyi yalnız yazılamayan ASCII için sakla. diff --git a/project-type/RESEARCH-LINE.md b/overlay/PUBLISHED-VERDICT.md similarity index 79% rename from project-type/RESEARCH-LINE.md rename to overlay/PUBLISHED-VERDICT.md index 6b2890e..725aba3 100644 --- a/project-type/RESEARCH-LINE.md +++ b/overlay/PUBLISHED-VERDICT.md @@ -1,45 +1,47 @@ -# Research-Line Conventions (language-agnostic) +# Published-Verdict Overlay (any project type) -Rules that apply to any Codechu **research line**: a method, the -pipeline that runs it, and an honest verdict about whether it works. -Language-specific extensions live under -[`lang//`](../lang/). +An **overlay**, not a project type: rules a repository adopts *on top +of* being a [library](../project-type/LIBRARY.md), +[tool](../project-type/TOOL.md) or +[application](../project-type/APPLICATION.md). Project types narrow; +overlays add. -Read first: [`STANDARDS.md`](../STANDARDS.md). +Read first: [`STANDARDS.md`](../STANDARDS.md), then your project type. -## 1. What makes a repository this type +## 1. When this overlay applies -A research line is a repository whose product is a **finding**. The -code exists to make the finding reproducible, and the honest status of -the finding is a first-class deliverable rather than a caveat at the -bottom. +Adopt it when the repository's product is a **claim** — a finding, a +score, a verdict — rather than only the software that produces it. The +code exists to make the claim reproducible, and the honest status of +the claim is a deliverable rather than a caveat at the bottom. -Three questions place a repo here — all three must be yes: +One question decides it: **could the verdict this repo publishes come +out negative, and would you publish it anyway?** If yes, the overlay +applies. If the repo only ships software and makes no claim about the +world, it does not. -| Question | Research line | -|---|---| -| Is there something to install and call from other software? | No | -| Does a human open it as a product? | No | -| Does it publish a verdict that could come out negative? | **Yes** | +The overlay was first written for a benchmark and a production line — +both of them tools by type. It does not replace the type's rules; it +adds obligations the type has no opinion about, and suspends two +vitrine bullets that assume a package. -Anything that answers yes to the first is a [library](LIBRARY.md); -yes to the second, an [application](APPLICATION.md). - -## 2. Two §7.1 rules do not apply here +## 2. Two §7.1 rules do not apply under this overlay [STANDARDS §7.1](../STANDARDS.md#71-readme-is-the-vitrine) is written for things that ship as packages. Two of its bullets have no referent -in a research line, and forcing them produces a dishonest README: +when the product is a claim, and forcing them produces a dishonest +README: - **"One quick example, 5–15 lines, that a reader can run right after - install."** There is nothing to install, and a line whose product is - a verdict cannot honestly promise that five lines produce a result. + install."** A repository whose product is a verdict cannot honestly + promise that five lines produce a result — the result is the point, + and it takes a run. Replace it with **§4's `## Run it`**: one command that runs today, offline, followed by a real captured trace. - **"Family table (sibling Codechu packages)."** What ties siblings - here is a shared method and identity, not a registry namespace. A - package table would list nothing. Say the relationship in a sentence - and link the sibling repository. + here is a shared method and identity, not a registry namespace — and + the sibling is often not published at all. Say the relationship in a + sentence and link the repository. Every other §7.1 rule and every §7.1 prohibition still holds. @@ -58,7 +60,7 @@ justification is only legible once the reader knows what is being justified. **Every doctrinal passage follows the concrete thing it defends.** -## 4. README is the vitrine — research-line skeleton +## 4. README is the vitrine — verdict skeleton ```markdown [hero image — ONE, ] @@ -90,7 +92,7 @@ defends.** ``` **Maximum nine `##` sections.** Above nine, GitHub's outline menu -becomes a wall. *Incident: a research-line README carried thirteen, +becomes a wall. *Incident: one such README carried thirteen, six of them beginning with the word "What" — unnavigable in a sidebar that truncates.* @@ -128,9 +130,10 @@ bare `
`; a fenced block renders as ``.* Indented blocks get no syntax highlighting — reserve them for non-typable ASCII. -**Commands must fit the column.** *Incident: `# 80 tests, no network` -rendered as `# 80 tests, no networ` — the first command a reader sees, -cut off.* Keep command lines under ~60 characters. +**A code fence clips; it does not wrap.** Budget the column your +readers are on, and see [STANDARDS §7.1](../STANDARDS.md#71-readme-is-the-vitrine) +before quoting a number — the one this document used to quote was +retracted for having been measured against nothing. **Two blockquote lines in one paragraph collapse into one.** *Incident: the best sentence in a README had been rendering as a single @@ -183,7 +186,7 @@ limitation. ## 8. Every number carries its record -A research line is believed on its numbers, so a number without an +A repository under this overlay is believed on its numbers, so a number without an openable record is worse than no number. - A number printed in the README, the changelog, or any durable @@ -213,7 +216,7 @@ when a cross-reference dies. - [ ] Badge row on one source line, every badge linked - [ ] Lede names the runtime ("Python", "stdlib-only") — grep for it - [ ] Status stamp above the fold, full `## Status` in the lower third -- [ ] `## Run it` present, fenced, language-tagged, offline, ≤60-char lines +- [ ] `## Run it` present, fenced, language-tagged, and offline - [ ] A real captured trace, literal, with a test binding it - [ ] ≤9 `##` sections, no two starting with the same word - [ ] Documentation as a table with a "when you need it" column diff --git a/overlay/README.md b/overlay/README.md new file mode 100644 index 0000000..16a617f --- /dev/null +++ b/overlay/README.md @@ -0,0 +1,14 @@ +# Overlays + +An **overlay** is a discipline a repository adopts *in addition to* its +project type. Project types narrow (a library is a kind of repository); +overlays add (a library may or may not publish verdicts). + +| Overlay | Adopt it when | Rules | +|---|---|---| +| **Published verdict** | The repo's product is a claim — a finding, a score, a verdict — that could come out negative | [PUBLISHED-VERDICT.md](PUBLISHED-VERDICT.md) | + +Read in order: [`STANDARDS.md`](../STANDARDS.md) → +[`project-type/`](../project-type/) → [`lang/`](../lang/) → overlays. +An overlay may suspend a specific rule from an earlier layer, but it +must say which rule and why; silence means the earlier layer stands. diff --git a/project-type/README.md b/project-type/README.md index c1f6337..ed399ec 100644 --- a/project-type/README.md +++ b/project-type/README.md @@ -7,7 +7,7 @@ Language-specific extensions live in [`lang/`](../lang/). |---|---|---| | **Library** | Reusable component published to a package registry, consumed by other software | [LIBRARY.md](LIBRARY.md) | | **Application** | End-user product installed and run by a human | [APPLICATION.md](APPLICATION.md) | -| **Research line** | A method, the pipeline that runs it, and an honest verdict about whether it works | [RESEARCH-LINE.md](RESEARCH-LINE.md) | +| **Tool** | Software a developer installs and runs by hand to produce an artefact | [TOOL.md](TOOL.md) | | **Proprietary library** | Closed-source / source-available library sold to customers | [PROPRIETARY-LIBRARY.md](PROPRIETARY-LIBRARY.md) | | **Proprietary application** | Closed-source / source-available end-user application | [PROPRIETARY-APPLICATION.md](PROPRIETARY-APPLICATION.md) | @@ -26,7 +26,7 @@ codechu-org/ ├── project-type/ │ ├── LIBRARY.md # any library (OSS-friendly) │ ├── APPLICATION.md # any app (OSS-friendly) -│ ├── RESEARCH-LINE.md # method + pipeline + verdict +│ ├── TOOL.md # developer runs it, gets an artefact │ ├── PROPRIETARY-LIBRARY.md # closed-source library extras │ └── PROPRIETARY-APPLICATION.md # closed-source app extras └── lang/ @@ -37,3 +37,6 @@ codechu-org/ ``` Read in order: STANDARDS → project-type → lang. Each layer narrows. +Disciplines that *add* rather than narrow — a repository whose product +is a claim, for instance — live in [`overlay/`](../overlay/) and are +adopted on top of a type. diff --git a/project-type/TOOL.md b/project-type/TOOL.md new file mode 100644 index 0000000..e4314c9 --- /dev/null +++ b/project-type/TOOL.md @@ -0,0 +1,128 @@ +# Tool Conventions (language-agnostic) + +Rules that apply to any Codechu **tool**: software a developer installs +and runs by hand to produce an artefact — a report, a conversion, a +measurement — rather than software another program imports, or a +product a consumer opens. Language-specific extensions live under +[`lang//`](../lang/). + +Read first: [`STANDARDS.md`](../STANDARDS.md). + +## 1. What makes a repository this type + +| Question | Tool | +|---|---| +| Does other software import it and call its API? | No — that is a [library](LIBRARY.md) | +| Does a non-technical user open it as a product? | No — that is an [application](APPLICATION.md) | +| Does a developer install it and invoke it to get an artefact? | **Yes** | + +The boundary matters because `APPLICATION.md` assumes a consumer +product: distribution channels, an update mechanism, a telemetry +policy, a first-run experience, settings state, localisation. A tool +has none of those and should not be made to pretend it does. What it +has instead is a command-line contract and an obligation to be +provable offline. + +## 2. The CLI surface is the public API + +Flags, subcommand names, exit codes and the shape of what is printed +are the contract. SemVer applies to all four. + +- **Renaming or removing a flag is a breaking change.** So is changing + what an exit code means, or the schema of a machine-readable output. +- **Exit codes must separate three outcomes**: it ran and the answer is + yes; it ran and the answer is no; it did not run. A tool that returns + 0 for "could not measure" turns an absence into a result, and the + caller cannot tell. *Incident: a gate returned `COMPLETE` with exit 0 + on a run that had never been measured.* +- **Machine-readable output carries a schema version**, and a reader of + an older version is told to upgrade rather than handed a silent + misparse. + +## 3. It must be provable with nothing + +Ship one command that exercises the whole pipeline with **no network, +no credentials, no model, no configuration** — and make it the first +command in the README. It is the only claim a reader can check before +deciding to trust the tool with anything real. + +A tool that can only be demonstrated against a paid endpoint cannot be +evaluated by the person deciding whether to adopt it. + +## 4. It refuses rather than guesses + +When an input is missing or malformed, stop and name what is missing. +Do not infer, default, or produce a plausible artefact — a wrong +artefact that looks right costs more than no artefact. + +- A stop names *what* is missing and *what would unblock it*. +- A stop is not an exception traceback. *Incident: four module entry + points answered a wrong path with a raw traceback — the opposite of + what the tool claimed about itself everywhere else.* + +## 5. Every artefact carries its provenance + +Anything the tool writes that could later be quoted — a report, a +score, a converted file — carries the tool version, the inputs, and +whatever seeds or settings would be needed to produce it again. + +**The version stamp must come from one place.** *Incident: a release +bumped the version in the packaging metadata and left three other +records behind, so reports produced by that release were stamped with a +version that did not produce them.* Where a version is recorded more +than once, a test asserts the records agree. + +## 6. Long runs are watchable + +A run that takes minutes prints progress as it goes — unbuffered, to a +stream the operator can follow, with a measured estimate rather than a +guessed one. Output that appears only at the end is indistinguishable +from a hang, and the operator's only recourse is to kill it. + +Do not swallow output in a buffer for tidiness. If filtering is needed, +filter line-by-line. + +## 7. Distribution + +- Publish to the language's package index; recommend the isolated + installer (`pipx` and equivalents) first, because a tool goes on the + PATH rather than into a project's dependency tree. +- The import/command name and the published package name may differ — + say so in the README, once, where the install command is. +- No update mechanism, no telemetry, no first-run wizard. If a tool + wants any of those, ask first whether it is really an application. + +## 8. README is the vitrine — tool skeleton + +The vitrine principle from +[STANDARDS §7.1](../STANDARDS.md#71-readme-is-the-vitrine) applies with +a tool-flavoured skeleton: + +```markdown +[hero: a terminal cast or a screenshot of real output] + +# tool-name + +[badge row — one source line, every badge linked] + +*[tagline — one italic sentence]* + +[lede: what goes in, what comes out, what runtime it needs] + +## Install & run the offline proof first, then the real invocation +## What you get the artefact itself, captured, not described +## Commands a table; the heading must not carry a count +## How it works the mechanism, briefly +## Limitations what it cannot do, and what would change that +## Documentation table with a "when you need it" column +--- +[footer: Contributing · Changelog · License] +``` + +A tool whose product is a claim about the world — a benchmark, a +grader, a measurement line — additionally adopts +[`overlay/PUBLISHED-VERDICT.md`](../overlay/PUBLISHED-VERDICT.md). + +The prohibition list from §7.1 still holds: no full options reference +(that is `docs/CLI.md`), no recipes cookbook, no architecture deep +dive.