Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 25 additions & 15 deletions STANDARDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand Down Expand Up @@ -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;
Expand All @@ -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 `<pre>` with no highlighting;
reserve indentation for non-typable ASCII.
Expand Down Expand Up @@ -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/<name>/`](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

Expand Down
31 changes: 20 additions & 11 deletions STANDARDS.tr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand Down Expand Up @@ -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
Expand All @@ -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 `<pre>` olarak render olur, highlight almaz;
girintiyi yalnız yazılamayan ASCII için sakla.
Expand Down
71 changes: 37 additions & 34 deletions project-type/RESEARCH-LINE.md → overlay/PUBLISHED-VERDICT.md
Original file line number Diff line number Diff line change
@@ -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/<name>/`](../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.

Expand All @@ -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, <p align="center">]
Expand Down Expand Up @@ -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.*

Expand Down Expand Up @@ -128,9 +130,10 @@ bare `<pre>`; a fenced block renders as
`<div class="highlight highlight-source-shell">`.* 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
14 changes: 14 additions & 0 deletions overlay/README.md
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 5 additions & 2 deletions project-type/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |

Expand All @@ -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/
Expand All @@ -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.
Comment on lines 39 to +42
Loading