From 54bee34bfaca6deda8b2b63b01e7d26598cfb7ce Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 27 Jul 2026 18:49:59 +0100 Subject: [PATCH 1/2] docs: finish instantiating the RSR docs skeleton for technical-notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs-template skeleton (adopted in #11) was never actually filled in for this repo: docs/architecture.adoc, docs/contributing.adoc, docs/usage.adoc and docs/troubleshooting.adoc still carried unfilled placeholders and generic RSR boilerplate describing a built/tested software product (just recipes, an HTTP API, Rust source paths) that does not exist here — this repo is a documentation archive of citable technical notes with no source code, build, or test suite. Root ARCHITECTURE.md/GOVERNANCE.md/MAINTAINERS were similarly unedited scaffold text, and MAINTAINERS/.github/CODEOWNERS/.github/funding.yml still pointed at the template's literal default owner (@metadatastician) instead of this repo's real owner (@hyperpolymath, confirmed via git history and existing SPDX headers). Rewrote all of the above to describe the repo truthfully and minimally (publishing/citation process instead of a fictional software architecture), fixed the stray :revdate: 2026-MM-DD placeholder in the ADR template, dropped a dead link to a nonexistent SECURITY.md, and trimmed mise.toml from a full generic-language toolchain list down to what this repo actually needs (git, typst). No {{...}} placeholders, template-validation scripts, justfile stubs, or .zig sources were found in this checkout, so those cure steps do not apply here. Co-Authored-By: Claude Opus 5 --- .github/CODEOWNERS | 2 +- .github/funding.yml | 2 +- ARCHITECTURE.md | 74 +++++++++++++++------------ GOVERNANCE.md | 83 ++++++++++++++----------------- MAINTAINERS | 40 ++++----------- docs/architecture.adoc | 80 +++++++++++++++-------------- docs/contributing.adoc | 78 ++++++++++++++--------------- docs/decisions/0001-template.adoc | 2 +- docs/troubleshooting.adoc | 63 ++++++++++++----------- docs/usage.adoc | 83 +++++++++++-------------------- mise.toml | 59 ++-------------------- 11 files changed, 235 insertions(+), 331 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7f60a0c..65a15d3 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,7 +1,7 @@ # Code Owners # Default: All contributors with write access are code owners -* @metadatastician +* @hyperpolymath # For specific paths, add explicit owners below # Example: diff --git a/.github/funding.yml b/.github/funding.yml index e4f7c07..0eda8fd 100644 --- a/.github/funding.yml +++ b/.github/funding.yml @@ -1,4 +1,4 @@ # Funding Configuration # See: https://docs.github.com/en/repositories/managing-your-repositorys-custom-fields/displaying-a-sponsor-button-in-your-repository -github: metadatastician +github: hyperpolymath diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 607e3d8..b998e55 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,47 +1,59 @@ -# Architecture + -## Overview +# Architecture -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. +`technical-notes` is a documentation archive, not a software project: +it holds short, citable technical notes (Markdown, optionally with a +Typst source and rendered PDF) that are individually deposited on +Zenodo with a DOI. There is no source code, no build system, and no +runtime component. -## Directory Structure +## Layout ``` . -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation +├── README.md # index of published notes (title, date, DOI) +├── .md # note source (Markdown) +├── .pdf # rendered note (optional, Typst-produced) +├── .typ # Typst source for the PDF (optional) +├── docs/ # process documentation (this file's siblings) +├── LICENSE / LICENSES/ # MPL-2.0 (repo tooling/process docs) + +│ # CC-BY-SA-4.0; individual notes carry +│ # their own licence at Zenodo-deposit time +└── .github/ # CI wrappers (governance, security scan) ``` -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized +## The invariant -## Dependencies +Every note listed in the README resolves to a real, citable Zenodo +record. If that link breaks, the repo has failed at its one job. -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility +## Publishing flow -## Security Considerations +There is no runtime to diagram; the only "flow" is authorial: -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed +``` +draft note (.md [+ .typ -> .pdf]) + | + v + README table entry (title, date, concept DOI, version DOI) + | + v + Zenodo deposit (direct API today; GitHub Release once the + Zenodo-GitHub integration is enabled — see README § Zenodo archiving) +``` -## Maintainability +## Out of scope -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently +* No source code, package, or binary is built or shipped from this repo. +* No API, service, or CLI. +* No automated test suite — there is no code to exercise. ---- +## See also -*Last updated: 2026-07-18* +* [docs/usage.adoc](docs/usage.adoc) — how to cite a note. +* [docs/contributing.adoc](docs/contributing.adoc) — how to add a new note. +* [docs/decisions/](docs/decisions/) — ADRs, historical record of why this shape. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index e27364c..a7f14c9 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,60 +1,49 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. + -## Roles and Responsibilities - -### Maintainers +# Governance -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support +`technical-notes` is a single-maintainer repository in the +`hyperpolymath` estate. There is no multi-maintainer or RFC process +here; estate-wide policy lives in +[`hyperpolymath/standards`](https://github.com/hyperpolymath/standards). -### Contributors +## Maintainer -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed +See [`MAINTAINERS`](MAINTAINERS) for who currently maintains this repo. -## Decision Making +## Decision making -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates +The maintainer accepts, revises, or declines contributions directly. +A non-trivial process change — how notes are drafted, versioned, or +archived — is recorded as an ADR in +[`docs/decisions/`](docs/decisions/) rather than decided ad hoc. -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers +## Licensing -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide +* Repository tooling and process documentation: MPL-2.0 or + CC-BY-SA-4.0 per the SPDX header on each file (see `LICENSE` / + `LICENSES/`). +* Each published note carries its own licence, set at Zenodo-deposit + time and recorded in that note's Zenodo metadata (see the root + `README.md` § Licence). -## Code of Conduct +## CI-enforced governance -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. +SPDX-header presence, licence consistency, secrets scanning, and +workflow security are enforced by the shared reusable workflow in +`hyperpolymath/standards`; see +[`.github/workflows/governance.yml`](.github/workflows/governance.yml) +and +[`.github/workflows/hypatia-scan.yml`](.github/workflows/hypatia-scan.yml). ## Communication -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* +* **Issues**: bugs or gaps in this repo — broken DOI links, wrong + citations, process gaps. +* **Pull requests**: proposed changes; see + [`CONTRIBUTING.md`](CONTRIBUTING.md). +* **Security**: follow estate policy in `hyperpolymath/standards` — + do not file security-relevant findings as public issues. diff --git a/MAINTAINERS b/MAINTAINERS index 37f6411..26e6ddd 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1,3 +1,8 @@ + + # Maintainers This file lists the current maintainers of this project. @@ -6,38 +11,15 @@ This file lists the current maintainers of this project. | Name | GitHub | Role | Since | |------|--------|------|-------| -| Metadatastician | @metadatastician | Primary | Project Start | +| Jonathan D.A. Jewell | [@hyperpolymath](https://github.com/hyperpolymath) | Primary | Project start | ## Emeritus Maintainers None at this time. -## Becoming a Maintainer - -To become a maintainer: - -1. Demonstrate consistent, high-quality contributions -2. Show understanding of the project's goals and architecture -3. Be active in code reviews and community discussions -4. Be nominated by an existing maintainer -5. Be approved by consensus of existing maintainers - -## Maintainer Responsibilities - -- Reviewing and merging pull requests -- Managing releases -- Triaging issues -- Enforcing code standards -- Mentoring new contributors -- Participating in decision-making - -## Maintainer Expectations - -- Respond to issues and PRs in a timely manner -- Follow the code of conduct -- Be transparent in decision-making -- Communicate clearly and respectfully - ---- +## Notes -*Last updated: 2026-07-18* +This is currently a single-maintainer repository, so there is no +formal "becoming a maintainer" process. See +[`GOVERNANCE.md`](GOVERNANCE.md) for how decisions are made and +[`CONTRIBUTING.md`](CONTRIBUTING.md) for how to propose a change. diff --git a/docs/architecture.adoc b/docs/architecture.adoc index ce69463..c14fbe2 100644 --- a/docs/architecture.adoc +++ b/docs/architecture.adoc @@ -1,78 +1,76 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> = Architecture — technical-notes -:revdate: 2026-MM-DD +:revdate: 2026-07-27 == System overview -One paragraph: what this project does and what it does not do. State the -*invariant* — the property that, if violated, would make the whole project -pointless. Future maintainers will read this paragraph first. +`technical-notes` is a documentation archive, not a running system. It +holds short, citable technical notes (Markdown, optionally with a Typst +source and rendered PDF) that are individually deposited on Zenodo with a +DOI. The invariant that matters: every note listed in the README resolves +to a real, citable Zenodo record. If that link breaks, the repo has +failed at its one job. == Component diagram -Replace this section with an ASCII or Mermaid diagram. Keep it under 20 -lines — anything bigger belongs in `architecture/`. +There is no runtime component graph. The only "flow" is authorial: [source] ---- -+------------------+ +------------------+ -| Component A | ---> | Component B | -+------------------+ +------------------+ - | - v -+------------------+ -| Component C | -+------------------+ +draft note (.md [+ .typ -> .pdf]) + | + v + README table entry (title, date, concept DOI, version DOI) + | + v + Zenodo deposit (direct API today; GitHub Release once the + Zenodo-GitHub integration is enabled) ---- == Data flow -For each external input, describe: - -* **Source**: where it comes from. -* **Validation**: what guarantees we enforce on entry. -* **Transformation**: high-level processing stages. -* **Sink**: where the result goes. +* **Source**: the maintainer's own drafting — no external input feed. +* **Validation**: none automated beyond estate governance CI (SPDX + headers, licence consistency, secrets scanning — see + `.github/workflows/governance.yml` and + `.github/workflows/hypatia-scan.yml`). +* **Transformation**: optional Typst → PDF render for notes that ship one. +* **Sink**: Zenodo (DOI-bearing deposit) and the README index. == Key invariants -Enumerate the load-bearing invariants of the system. Each should have: - -. A one-line statement. -. The code location(s) that enforce it. -. The failure mode if the invariant is violated. - -Example: - [cols="1,2,2,2", options="header"] |=== | # | Invariant | Enforced at | Failure mode | 1 -| All HTTP requests carry a valid `X-Request-ID`. -| `src/middleware/request_id.rs` -| Logs become unjoinable; correlation breaks. +| Every README row has a resolvable DOI link. +| Manual, at note-publish time. +| Citation breaks; the note becomes unfindable via its concept DOI. | 2 -| The output buffer is always flushed before exit. -| `src/main.rs:88-92` (Drop impl) -| Last ~16KB of log lost on crash. +| Every published note's licence matches its Zenodo deposit metadata. +| `.zenodo.json` for the deposited record; manual cross-check. +| Licence mismatch between GitHub and the archival copy. |=== == Dependencies -* **Internal**: list other hyperpolymath repos this depends on. -* **External**: SHA-pinned (see `Cargo.lock` / `deno.lock` / etc.). -* **Build-time**: tools required to build (just, deno, cargo, …). +* **Internal**: none — this repo does not depend on other hyperpolymath + repos. +* **External**: Zenodo (archival + DOI minting). +* **Build-time**: none to read a note; Typst only when producing a PDF + rendering of a note that has one. == Out of scope -Explicit non-goals. Things we deliberately do *not* do, with a one-line -reason for each. This section saves more time than the rest combined. +* No source code, package, or binary is built or shipped from this repo. +* No API, service, or CLI — there is nothing to run. +* No automated test suite — there is no code to exercise. == See also -* link:./usage.adoc[Usage] — consumer perspective. -* link:./contributing.adoc[Contributing] — developer setup. +* link:./usage.adoc[Usage] — how to cite a note. +* link:./contributing.adoc[Contributing] — how to add a new note. * link:./decisions/[ADRs] — historical record of why this shape. diff --git a/docs/contributing.adoc b/docs/contributing.adoc index 651eae0..53ee5a4 100644 --- a/docs/contributing.adoc +++ b/docs/contributing.adoc @@ -1,62 +1,60 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> = Contributing — technical-notes -:revdate: 2026-MM-DD +:revdate: 2026-07-27 == Audience -Developers working *on* `technical-notes`. For consumers (people calling -or depending on it) see link:./usage.adoc[usage.adoc]. +Developers working *on* `technical-notes` — i.e. adding or revising a +note, or improving the repo's own process documentation. For readers and +citers, see link:./usage.adoc[usage.adoc]. -== Local-dev setup +== What this repo is -Prerequisites — the minimum versions and where to get them: +A documentation archive: short technical notes, each individually +archived on Zenodo with a DOI. There is no source code, build, or test +suite. -* `` v`` — ``. -* `` v`` — ``. -* GPG signing key configured (estate policy — all commits must be - signed). See - link:https://github.com/hyperpolymath/standards/blob/main/docs/secure-coding-training.md[standards/docs/secure-coding-training.md]. +== Local-dev setup -One-shot setup: +No toolchain is required to read or edit a note — they are plain +Markdown. If a note ships a Typst-rendered PDF, Typst is needed to +reproduce it: [source,bash] ---- git clone git@github.com:hyperpolymath/technical-notes.git cd technical-notes -just setup # installs deps, sets up hooks -just test # runs the full test suite +typst compile .typ .pdf # only if the note has a .typ source ---- -== Running tests - -* **Unit**: `just test-unit` — fast, no I/O. -* **Integration**: `just test-int` — uses real services (database, - HTTP, etc.). Estate policy: prefer real over mocked - (see `feedback_integration_tests_real_db` in maintainer's memory). -* **Property**: `just test-prop` — randomised, slower; budget - documented in `docs/proof-debt.md` if applicable. -* **Full**: `just test` — runs all of the above. +A GPG signing key must be configured — estate policy requires all +commits to be signed. See +link:https://github.com/hyperpolymath/standards/blob/main/docs/secure-coding-training.md[standards/docs/secure-coding-training.md]. -== Code style +== Conventions -We enforce style via CI (governance-reusable.yml from hyperpolymath/standards). -Locally: - -[source,bash] ----- -just fmt # auto-format -just lint # static checks ----- +There is no code, so "style" here means documentation conventions, +enforced via CI (`governance.yml`, wrapping +`governance-reusable.yml` from `hyperpolymath/standards`): * All commits must be **GPG-signed** (CI enforces; see link:https://github.com/hyperpolymath/standards[standards]). -* All source files must carry an **SPDX-License-Identifier** header +* All files must carry an **SPDX-License-Identifier** header (CI enforces). * Conventional commits — `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `ci`, `revert` (CHANGELOG is auto-generated from these via link:https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`changelog-reusable.yml`]). +== Adding a new note + +. Draft the note as Markdown; add a `.typ` source and rendered `.pdf` + if you want a typeset version. +. Deposit it on Zenodo (direct API today, or via a GitHub Release once + the Zenodo–GitHub integration is enabled) to mint a DOI. +. Add a row to the README table: title, date, concept DOI, latest + version DOI. + == Branching & PR workflow . Branch off `main` as `claude/` (for AI agents) or @@ -68,23 +66,19 @@ just lint # static checks (see standards#196 audit and policies). . CI must be green. The PR auto-merges when checks pass + reviews land. -== Adding a new dependency - -. State the *why* in the PR body — what does this dependency unlock? -. Check provenance (maintained, audited, no malicious history). -. Pin to a SHA, not a tag. -. Update `docs/architecture.adoc#Dependencies`. - == Adding an ADR -When you make a non-obvious design decision, write it down: +When you make a non-obvious process decision — e.g. how notes are +versioned, licensed, or archived — write it down: . Copy `docs/decisions/0001-template.adoc` → `0002-.adoc`. . Fill in: Context, Decision, Consequences, Alternatives. -. Link the ADR from the README or relevant code as a comment. +. Link the ADR from the README or relevant doc as a comment. == Reporting issues -* Bugs in `technical-notes`: file at `hyperpolymath/technical-notes/issues`. +* Issues with `technical-notes` itself — a broken DOI link, a wrong + citation, a process gap: file at + `hyperpolymath/technical-notes/issues`. * Estate-wide concerns (policy, conventions, CI): file at `hyperpolymath/standards/issues`. diff --git a/docs/decisions/0001-template.adoc b/docs/decisions/0001-template.adoc index 0ebe392..7568a04 100644 --- a/docs/decisions/0001-template.adoc +++ b/docs/decisions/0001-template.adoc @@ -1,7 +1,7 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> = ADR-0001 — Use Architecture Decision Records -:revdate: 2026-MM-DD +:revdate: 2026-07-27 :status: ACCEPTED == Context diff --git a/docs/troubleshooting.adoc b/docs/troubleshooting.adoc index c16b07c..3a0babc 100644 --- a/docs/troubleshooting.adoc +++ b/docs/troubleshooting.adoc @@ -1,7 +1,7 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> = Troubleshooting — technical-notes -:revdate: 2026-MM-DD +:revdate: 2026-07-27 This file is a *living FAQ* — known failure modes and recovery paths. Add a new entry every time you debug something that took more than 15 @@ -9,49 +9,54 @@ minutes; future-you (and other maintainers) will thank you. == Known failure modes -=== `` +=== A note's DOI link 404s, or resolves to the wrong version -**Symptom**: short reproduction. What does the user see? +**Symptom**: the README's DOI link does not resolve, or resolves to an +unexpected version of a note. -**Cause**: root cause (one or two sentences). +**Cause**: a concept DOI (`10.5281/zenodo.`) always redirects to +the *latest* version; a version DOI (`10.5281/zenodo.`) is +pinned to that one specific revision. Mixing the two up in the README or +in a citation is the usual cause. -**Fix**: -[source,bash] ----- - ----- +**Fix**: check the note's Zenodo record page directly, then correct the +README link to the DOI you actually mean — concept DOI for "latest", +version DOI for "this exact revision". -**Avoidance**: how to not hit this again (config setting, doc link, etc.). +**Avoidance**: state explicitly in the README (as the current table +does) which DOI is the concept DOI and which is a specific version. --- -=== `` +=== Governance or Hypatia-scan CI is red -(Replace this and the above example with real entries as you encounter -them.) +**Symptom**: `.github/workflows/governance.yml` or +`.github/workflows/hypatia-scan.yml` fails. -== Diagnostic toolkit +**Cause**: both are thin wrappers over reusable workflows in +`hyperpolymath/standards`; failures are almost always a missing SPDX +header, a licence-consistency issue, or an upstream pin change in +`standards`. -When something is wrong, run these first: +**Fix**: read the failing job's log — it names the specific file or +rule. If the failure looks unrelated to anything changed in this repo, +cross-check `hyperpolymath/standards` for a recent policy change. -[source,bash] ----- -just doctor # runs all available self-checks -just version # prints the version & build hash -just log-tail # last N lines of logs ----- +**Avoidance**: keep an SPDX header on every file, and don't hand-edit +`LICENSE` or `LICENSES/`. == When to escalate -. Filed an issue with: version, OS, exact command, full error output, - and the symptom in plain English. -. Linked from the issue: the relevant ADR(s) and any related issues. -. For *security*-relevant findings, see - link:./../SECURITY.md[SECURITY.md] — do **not** file public issues. +. File an issue with: the symptom in plain English, the exact link or + command involved, and what you expected instead. +. For *security*-relevant findings, follow the security policy in + `hyperpolymath/standards` — do **not** file public issues for those. == Where to look for more help -* `docs/architecture.adoc` — internals. +* `docs/architecture.adoc` — how the archive is organised. * `docs/decisions/` — historical record of why things are this shape. -* `https://github.com/hyperpolymath/technical-notes/issues?q=is%3Aissue+` — has anyone hit this before? -* `https://github.com/hyperpolymath/standards/issues` — for estate-wide problems. +* `https://github.com/hyperpolymath/technical-notes/issues` — has anyone + hit this before? +* `https://github.com/hyperpolymath/standards/issues` — for estate-wide + problems. diff --git a/docs/usage.adoc b/docs/usage.adoc index fe6e2af..3ca3c14 100644 --- a/docs/usage.adoc +++ b/docs/usage.adoc @@ -1,81 +1,56 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com> = Usage — technical-notes -:revdate: 2026-MM-DD +:revdate: 2026-07-27 == Audience -This document is for *consumers* of `technical-notes` — people who depend -on it, call it, or include it. For developers working *on* it, see -link:./contributing.adoc[contributing.adoc]. +This document is for *readers and citers* of `technical-notes` — people +who want to read a note or cite it in their own work. For people +drafting or revising a note, see link:./contributing.adoc[contributing.adoc]. -== Quickstart +== Reading a note -The shortest path from zero to a working call: +Each note lives at the repo root as a Markdown file (`.md`), listed +in the README table. Some notes also ship a Typst source (`.typ`) +and a rendered PDF (`.pdf`) as a typeset reading copy. -[source,bash] ----- -# 1. Install -just install # or: cargo install --path . / deno task install - -# 2. Configure -cp examples/config.example.toml ./config.toml -# Edit minimal required fields. - -# 3. Run -just run # or the equivalent for your language ----- +== Citing a note -Expected output: +Use the **concept DOI** from the README table — it always resolves to +the latest version, so citations do not go stale as a note is revised: [source] ---- -technical-notes v0.0.0 -Listening on 127.0.0.1:8080 +Jewell, J. D. A. (). . Zenodo. https://doi.org/ ---- -== Common use cases - -For each canonical use case, give: - -. A one-line statement of the goal. -. The minimal invocation. -. Expected output / side effect. +To cite a specific revision instead of "latest", use that version's DOI +(also listed in the README table). -=== Use case 1: +== Licensing -(Replace with real content.) - -=== Use case 2: - -== Configuration reference - -Document every configurable field. Keep this section authoritative — if -the code grows a new option, this table must grow too (CI can be wired -to enforce this). - -[cols="1,1,1,3", options="header"] -|=== -| Field | Type | Default | Meaning - -| `` | `` | `` | -|=== +Each note's licence is set at Zenodo-deposit time and recorded in that +note's own Zenodo metadata; it is not necessarily the same licence as +this repository's own tooling and process documentation. See the root +`README.md` § Licence and the per-file SPDX headers in this repo for +those. == Stability guarantees -Be explicit: - -* **Stable**: API surfaces that follow SemVer (breaking change = major bump). -* **Unstable**: behind a flag / pre-1.0 / explicitly marked. -* **Internal**: documented for reference but no compatibility promise. +* A note's **content**, once deposited, is versioned — a revision gets a + new version DOI under the same concept DOI; nothing is silently edited + in place on Zenodo. +* The **README table** is the index of record for which notes exist and + their current DOIs. == Limits & known constraints -* Maximum supported ``: ``. -* `` is not yet implemented; track at issue `#`. -* On ``, `` behaves differently because ``. +* The Zenodo–GitHub integration is not yet enabled (see README § Zenodo + archiving); until it is, new versions are deposited directly via the + Zenodo API rather than via a GitHub Release. == See also -* link:./architecture.adoc[Architecture] — how it works internally. +* link:./architecture.adoc[Architecture] — how the archive is organised. * link:./troubleshooting.adoc[Troubleshooting] — when things go wrong. diff --git a/mise.toml b/mise.toml index 6dd983f..5cd3662 100644 --- a/mise.toml +++ b/mise.toml @@ -1,57 +1,6 @@ [tools] -# Language runtimes -node = "latest" -python = "latest" -rust = "latest" -go = "latest" -zig = "latest" -java = "latest" -bun = "latest" -denojs = "latest" - -# Package managers -npm = "latest" -yarn = "latest" -pnpm = "latest" -pip = "latest" -cargo = "latest" -go-task = "latest" - -# Formatting & Linting -gofmt = "latest" -black = "latest" -isort = "latest" -ruff = "latest" -prettier = "latest" -shfmt = "latest" -stylua = "latest" - -# Build tools -cmake = "latest" -make = "latest" -ninja = "latest" - -# Shell tools +# technical-notes is a documentation archive: no source code, no build, +# no test suite. git is the only tool required to work on it; typst is +# needed only to reproduce a note's rendered PDF from its .typ source. git = "latest" -gnu-sed = "latest" -gnu-tar = "latest" -gnu-grep = "latest" - -# Testing -vitest = "latest" -pytest = "latest" -jest = "latest" - -[env] -# Common environment variables -NODE_ENV = "development" -PYTHONDONTWRITEBYTECODE = "1" -PYTHONUNBUFFERED = "1" - -# Task runner alias -[alias] -task = "go-task" -build = "cargo build --release || npm run build || go build" -test = "cargo test || npm test || go test ./..." -lint = "ruff check . || prettier --check . || black --check ." -fmt = "ruff format . || prettier --write . || black ." +typst = "latest" From 54f508b3f580bd8c43ab8dc5dde4ccc57add5e94 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 13 Aug 2026 05:21:29 +0100 Subject: [PATCH 2/2] fix(ci): update reusable workflow SHAs to @7fdc2705df74b4e352d2a1cde3e87a5923fdf329 Part of estate-wide standards#426 remediation - Batch 13 SHA update. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- .github/workflows/governance.yml | 2 +- .github/workflows/hypatia-scan.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index 62bbc98..e344b40 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -31,4 +31,4 @@ permissions: jobs: governance: - uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@81dbf2dd854b1444fd6236fa2352474383b2c2b9 \ No newline at end of file + uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@7fdc2705df74b4e352d2a1cde3e87a5923fdf329 \ No newline at end of file diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index 2e7e939..92f38eb 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -25,5 +25,5 @@ permissions: jobs: hypatia: - uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@81dbf2dd854b1444fd6236fa2352474383b2c2b9 + uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@7fdc2705df74b4e352d2a1cde3e87a5923fdf329 secrets: inherit \ No newline at end of file