From 23cf64883351c4ebb2d82bf66c3a59b9995b4461 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Gonz=C3=A1lez=20Paredes?= Date: Thu, 1 Oct 2026 21:27:45 +0200 Subject: [PATCH 1/2] archive: add unpublished content/archive/ and retire dimensions-as-types Add content/archive/ for retired (superseded or abandoned) proposals: kept in git, excluded from the Quartz site via ignorePatterns. Document the retirement procedure in AGENTS.md and the new `retired` status. Retire shared/dimensions-as-types (superseded by connectivities-as-types): move it to archive/, drop its index entry (listed in an unrendered Archived comment instead), and turn inbound wikilinks into GitHub links so the published pages have no dead links. --- AGENTS.md | 26 ++++++++++++++++++- README.md | 3 ++- .../dimensions-as-types.md | 6 ++--- content/index.md | 9 ++++++- .../connectivities-as-types.md | 8 +++--- ...onnectivities-as-types_dependent-typing.md | 2 +- .../dimension-generic-fields.md | 12 ++++----- .../typed_dimensions.py | 2 +- quartz.config.ts | 4 +-- 9 files changed, 52 insertions(+), 20 deletions(-) rename content/{shared => archive}/dimensions-as-types.md (99%) diff --git a/AGENTS.md b/AGENTS.md index da1b48c..d585f72 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,7 @@ content/ knowledge/ # reference material proposals lean on (not proposals) / # one subdirectory per topic area .md # a reference note + archive/ # retired proposals, kept in git (NOT published — see ignorePatterns) templates/ # idea template (NOT published — see ignorePatterns) ``` @@ -39,6 +40,9 @@ content/ external prior art) that proposals can cite. These are not proposals: they use plain `title`/`description`/`tags` frontmatter with no `author` or `status`, and they are indexed under **Knowledge** in `content/index.md`. +- **`archive/`** — flat directory of retired proposals (superseded or + abandoned). Kept in git so they are not lost, but excluded from the published + site. See [Retiring a proposal](#retiring-a-proposal). - An accepted idea that becomes concrete graduates to real work in gt4py (a PR, or a formal ADR in the gt4py repo); it can then be retired from here. @@ -64,6 +68,7 @@ content/ - `reviewed` — at least one person (e.g. the author) has reviewed the content. - `final` — clear proposal that could be implemented, but should still be reviewed by another person. + - `retired` — superseded or abandoned; only for documents in `archive/`. 3. Before writing, **skim the index and existing proposals** for overlap; link related/conflicting documents with `[[wikilinks]]` and call out the conflict @@ -109,10 +114,29 @@ and agents consult. It must stay current and keyword-rich: - Prefer one consistent keyword vocabulary across entries (e.g. reuse `dace`, `unstructured`, `type-system`) so related ideas cluster and conflicts surface. +## Retiring a proposal + +A proposal that is superseded or abandoned (but worth keeping) moves to +`content/archive/`, which is excluded from the published site. In one change: + +1. `git mv` it to `content/archive/.md` (a multi-file proposal moves as + its whole `/` directory). Retiring a `shared/` proposal needs PR review + like any other `shared/` change. +2. Set `status: retired` and, if it was superseded, add + `superseded_by: ` to its frontmatter. +3. Remove its entry from **Personal**/**Shared** in `content/index.md` and add + it to the `Archived` HTML comment at the bottom of the index (same keywords, + plus what supersedes it). The comment is not rendered, but keeps the archived + idea visible to anyone cross-checking a new proposal against the source. +4. Rewrite every inbound `[[wikilink]]` from published documents into a plain + GitHub link (`[label](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/.md)`); + a wikilink to an unpublished note is a dead link on the site. Wikilinks + *inside* archived documents can stay as they are. + ## Publishing notes - `baseUrl` in `quartz.config.ts` must match the final GitHub Pages URL of this repo; update it if the repo moves. -- Anything under `templates/`, `private/`, or `.obsidian/` is excluded from the +- Anything under `templates/`, `private/`, `archive/`, or `.obsidian/` is excluded from the published site (`ignorePatterns`). Use `draft: true` in frontmatter to keep an in-progress note out of the published site while still committing it. diff --git a/README.md b/README.md index 338289b..ab48a46 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ See [`AGENTS.md`](AGENTS.md) for the structure, authoring workflow, and the rule for keeping [`content/index.md`](content/index.md) useful. Every proposal must include a `status` field in its frontmatter: `draft` -(default), `reviewed`, or `final`. +(default), `reviewed`, `final`, or `retired` (archived; see `AGENTS.md`). ## Structure @@ -26,6 +26,7 @@ content/ _research.md # optional appendix: background, research, prior art _.md # optional further appendices shared/ # proposals that are discussed by the team (only touch with PR review) + archive/ # retired proposals, kept in git (NOT published — see ignorePatterns) templates/ # idea template (NOT published — see ignorePatterns) quartz.config.ts # Quartz config (set baseUrl to the Pages URL) quartz.layout.ts # Quartz layout diff --git a/content/shared/dimensions-as-types.md b/content/archive/dimensions-as-types.md similarity index 99% rename from content/shared/dimensions-as-types.md rename to content/archive/dimensions-as-types.md index 329c897..e49c72e 100644 --- a/content/shared/dimensions-as-types.md +++ b/content/archive/dimensions-as-types.md @@ -4,15 +4,15 @@ description: "Make a concrete gt4py.next dimension a type (`class I(gtx.Dimensio author: havogt tags: [type-system, dimensions, type-checking, mypy, mypy-plugin, pyright, nominal-types, metaclass, migration, serialization, frontend, foast, extension-point] created: 2026-08-05 -status: superseded +status: retired +superseded_by: personal/egparedes/connectivities-as-types/connectivities-as-types --- > **Superseded** by > [[personal/egparedes/connectivities-as-types/connectivities-as-types|Connectivities as types]] > (gt4py ADR 0028, GridTools/gt4py#2899), which makes a dimension a class with > *type* identity (its qualified name) instead of the `(name, kind)` value -> identity and interning registry proposed here. Kept for reference until that -> proposal moves to `shared/`. +> identity and interning registry proposed here. > **TL;DR** A concrete dimension is currently an *instance* > (`I = Dimension("I")`), so `Field[Dims[I], float64]` is not a valid static diff --git a/content/index.md b/content/index.md index cf9d353..97af6d8 100644 --- a/content/index.md +++ b/content/index.md @@ -15,7 +15,6 @@ index current. (Keep entries and their keywords in sync with each document's `ta Proposals the group broadly agrees are implementation-ready. - [[shared/external-memory-for-dace-arrays/external-memory-for-dace-arrays|External workspace memory for DaCe temporary arrays]] — keywords: dace, backend, gpu, memory, temporary-arrays, workspace, cuda, hip, mempool, persistent, external, allocation, icon4py, performance -- [[shared/dimensions-as-types|Dimensions as types]] (superseded by [[personal/egparedes/connectivities-as-types/connectivities-as-types|Connectivities as types]]) — keywords: type-system, dimensions, type-checking, mypy, mypy-plugin, pyright, nominal-types, metaclass, migration, serialization, frontend, foast, extension-point diff --git a/content/personal/egparedes/connectivities-as-types/connectivities-as-types.md b/content/personal/egparedes/connectivities-as-types/connectivities-as-types.md index 0c8158b..5d51acf 100644 --- a/content/personal/egparedes/connectivities-as-types/connectivities-as-types.md +++ b/content/personal/egparedes/connectivities-as-types/connectivities-as-types.md @@ -53,8 +53,8 @@ status: draft > The remap typing it needs is the `Connectivity[NewD, D0]` rule of > [[personal/havogt/dimension-generic-fields/dimension-generic-fields|Generic dimensions and statically > typed staggering]], whose Part II also proposed the `Staggered[D]` shape -> used here. It **supersedes** [[shared/dimensions-as-types|Dimensions as -> types]]: the dimension design below (ADR 0028) replaces that note's +> used here. It **supersedes** [Dimensions as +> types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md): the dimension design below (ADR 0028) replaces that note's > `(name, kind)` value identity and interning registry with type identity, and > is stated here in full. It overlaps with > [[personal/havogt/mesh-and-first-class-halos/mesh-and-first-class-halos|A mesh concept with @@ -313,7 +313,7 @@ embeds its base's full tag, rule 1; a connectivity is *named in the IR* by its `offset_tag`, rule 7). The static view (checkers see nominal types) and the runtime view (equality is `is`) agree by construction, and the tag is a valid, unique IR string. This is the point on which this note supersedes -[[shared/dimensions-as-types|dimensions as types]] and GridTools/gt4py#2844, +[dimensions as types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md) and GridTools/gt4py#2844, which chose `(name, kind)` value equality plus an interning registry so that the test tree's many independently declared `IDim`s stay interchangeable. Under value equality the `typing` subscription cache aliases @@ -683,7 +683,7 @@ once dimensions are classes, the nested-class form is both simpler and statically meaningful. **`(name, kind)` value equality with an interning registry** (the design of -[[shared/dimensions-as-types|dimensions as types]] and GridTools/gt4py#2844). +[dimensions as types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md) and GridTools/gt4py#2844). Keeps independently declared same-named dimensions interchangeable and avoids the importability rule. Rejected because it decouples the Python type's identity from the IR's, needs a registry plus `copyreg` plus a custom diff --git a/content/personal/egparedes/connectivities-as-types/connectivities-as-types_dependent-typing.md b/content/personal/egparedes/connectivities-as-types/connectivities-as-types_dependent-typing.md index 81f1f26..250d8f7 100644 --- a/content/personal/egparedes/connectivities-as-types/connectivities-as-types_dependent-typing.md +++ b/content/personal/egparedes/connectivities-as-types/connectivities-as-types_dependent-typing.md @@ -307,7 +307,7 @@ proved. relations enumerating it. - **A brand per mesh entity (§7).** Nominal identity makes two independently declared `Vertex` classes distinct types, statically and at run time. The - `(name, kind)` equality of the superseded [[shared/dimensions-as-types|dimensions as types]] + `(name, kind)` equality of the superseded [dimensions as types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md) is the unbranded `Fin` of §7: equal names, interchangeable indices. Nominal identity is not sufficient to separate two *meshes* that share the same declarations, though — see below. diff --git a/content/personal/havogt/dimension-generic-fields/dimension-generic-fields.md b/content/personal/havogt/dimension-generic-fields/dimension-generic-fields.md index e5d0834..261f0f0 100644 --- a/content/personal/havogt/dimension-generic-fields/dimension-generic-fields.md +++ b/content/personal/havogt/dimension-generic-fields/dimension-generic-fields.md @@ -13,8 +13,8 @@ status: draft > constructor, and **dimension variables** (`TypeVar`/`TypeVarTuple` over > dimensions) so field operators can be generic in their dimensions. -> **Part I has been extracted** into [[shared/dimensions-as-types|Dimensions as -> types]]. §3 below is now a stub keeping only what Parts II and III refer back +> **Part I has been extracted** into [Dimensions as +> types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md). §3 below is now a stub keeping only what Parts II and III refer back > to; the requirements, rejected alternatives, migration plan and risks of the > base live in the shared document. Parts II and III stay here. @@ -120,7 +120,7 @@ redesign of §3; with today's instance-dimensions it indeed is not. ## 3. Part I — dimensions as types -**Extracted** to [[shared/dimensions-as-types|Dimensions as types]], together +**Extracted** to [Dimensions as types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md), together with its requirements, the rejected alternatives, the migration plan and the mypy-plugin removal it enables. Repeated here only insofar as Parts II and III below refer back to it: @@ -707,7 +707,7 @@ Stages 0–2 of the dtype plan are prerequisites for the *frontend* stages here (the binding utilities are shared); Part I/II stages are independent of dtype. 1. **Stage D0 — dimensions as types in `common`** (Part I): specified in - [[shared/dimensions-as-types|Dimensions as types]]; prerequisite for every + [Dimensions as types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md); prerequisite for every stage below. 2. **Stage D1 — typed shifts & staggering, static side** (Part II): `Staggered`, typed `Connectivity`, generated `Field.__call__` overloads; @@ -727,7 +727,7 @@ Stages 0–2 of the dtype plan are prerequisites for the *frontend* stages here ## 10. Risks and open questions 1. **The metaclass-overload mypy quirk** (see - [[shared/dimensions-as-types|Dimensions as types]]): call-site behavior is + [Dimensions as types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md)): call-site behavior is correct but the def-site suppression could break on a mypy upgrade; pinned by tests, with a notation-only fallback. Re-verified on **mypy 2.3** (2026-08-05) — the quirk and the suppression both still behave as described, @@ -740,7 +740,7 @@ Stages 0–2 of the dtype plan are prerequisites for the *frontend* stages here substitution operation is small (≤ 15), but `Field` has many operators; measure mypy runtime on a large downstream consumer before generalizing. 4. **Migration surface of Part I** is the largest cost item overall; it is - tracked in [[shared/dimensions-as-types|Dimensions as types]], not here. + tracked in [Dimensions as types](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/dimensions-as-types.md), not here. 5. **Canonical dims ordering with variables**: `Dims[D, K]` assumes the binding of `D` sorts before `K`; substitution re-validates, so a "wrongly ordered" binding today raises a validator error — decide whether to diff --git a/content/personal/havogt/dimension-generic-fields/typed_dimensions.py b/content/personal/havogt/dimension-generic-fields/typed_dimensions.py index 0d7c56f..35954c9 100644 --- a/content/personal/havogt/dimension-generic-fields/typed_dimensions.py +++ b/content/personal/havogt/dimension-generic-fields/typed_dimensions.py @@ -88,7 +88,7 @@ def __repr__(cls) -> str: # covers both, so `Dimension("I")` and `Dimension("I", VERTICAL)` are neither # equal nor hash-equal. The prototype ignores `kind` because it only ever # declares horizontal dimensions; a real implementation must include it (see - # `shared/dimensions-as-types`, "Design"). + # `archive/dimensions-as-types`, "Design"). def __eq__(cls, other: object) -> bool: if isinstance(other, DimensionMeta) or type(other).__name__ == "Dimension": return cls.value == other.value # type: ignore[attr-defined] diff --git a/quartz.config.ts b/quartz.config.ts index b0a89c9..b95a4d5 100644 --- a/quartz.config.ts +++ b/quartz.config.ts @@ -16,8 +16,8 @@ const config: QuartzConfig = { locale: "en-US", // NOTE: must match the GitHub Pages URL of wherever this repo finally lives. baseUrl: "gridtools.github.io/gt4py_knowledge", - // Folders excluded from the published site (templates/scratch/Obsidian dirs). - ignorePatterns: ["private", "templates", ".obsidian"], + // Folders excluded from the published site (templates/scratch/archive/Obsidian dirs). + ignorePatterns: ["private", "templates", "archive", ".obsidian"], defaultDateType: "modified", theme: { fontOrigin: "googleFonts", From 6e5f4a560792d2a9d1d91191e20e9ce1e656c3b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Gonz=C3=A1lez=20Paredes?= Date: Thu, 1 Oct 2026 21:33:09 +0200 Subject: [PATCH 2/2] AGENTS.md: archive/ keeps multi-file proposals as / (not flat) --- AGENTS.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d585f72..1c8a2eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,9 +40,10 @@ content/ external prior art) that proposals can cite. These are not proposals: they use plain `title`/`description`/`tags` frontmatter with no `author` or `status`, and they are indexed under **Knowledge** in `content/index.md`. -- **`archive/`** — flat directory of retired proposals (superseded or - abandoned). Kept in git so they are not lost, but excluded from the published - site. See [Retiring a proposal](#retiring-a-proposal). +- **`archive/`** — retired proposals (superseded or abandoned), one per + proposal with no `/` level: `.md`, or `/` for a + multi-file proposal. Kept in git so they are not lost, but excluded from the + published site. See [Retiring a proposal](#retiring-a-proposal). - An accepted idea that becomes concrete graduates to real work in gt4py (a PR, or a formal ADR in the gt4py repo); it can then be retired from here. @@ -129,7 +130,9 @@ A proposal that is superseded or abandoned (but worth keeping) moves to plus what supersedes it). The comment is not rendered, but keeps the archived idea visible to anyone cross-checking a new proposal against the source. 4. Rewrite every inbound `[[wikilink]]` from published documents into a plain - GitHub link (`[label](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/.md)`); + GitHub link to its archived path + (`[label](https://github.com/GridTools/gt4py_knowledge/blob/main/content/archive/.md)`, + or `…/archive//.md` for a multi-file proposal); a wikilink to an unpublished note is a dead link on the site. Wikilinks *inside* archived documents can stay as they are.