From 326016e805517141c755439d368d462ee9c2d64b Mon Sep 17 00:00:00 2001 From: Denis Chevalier Date: Tue, 11 Aug 2026 01:07:11 +0200 Subject: Add CONTRIBUTING.md --- CONTRIBUTING.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6847e39 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,158 @@ +# Contributing to the SAME Analog Modular Ecosystem Specification + +Thank you for your interest in contributing to the **SAME Analog Modular +Ecosystem**. + +Because SAME is a metrology-grade computing specification targeting +$10\text{ ppm}$ precision and $90\text{ dB}$ SNR, we maintain strict +engineering, mathematical, and procedural standards for all contributions. This +guide outlines how to set up your environment, write compliant Typst markup, +enforce our executable math paradigm, and submit pull requests. + +## 1. The Executable Specification Paradigm + +The defining principle of this repository is that **the specification is its own +test suite**. + +We do not manually transcribe calculated values into prose. Every mathematical +claim, noise derivation, tolerance budget, and physical scaling law presented in +the text must be directly accompanied by a compile-time assertion using our +custom metrology library (`lib/assert-aeq.typ` and `lib/apply-prefix.typ`). + +### The Rule of Zero-Copy Math + +When adding or modifying any numerical derivation: + +1. **Calculate programmatically:** Define variables using Typst math expressions + and SI helpers. +2. **Assert sanity at compile time:** Pass the calculated variable and the + expected target through `#assert-aeq`. +3. **Typeset the output:** Render the expression using standard Typst math + markup. + +#### Example + +```typst +#let v_noise_excess = ( + 5 * calc.pow(10, -15 / 20) * calc.sqrt(20000) * calc.pow(10, -6) +) +// 1. Compile-time assertion using named SI prefixes +#assert-aeq(v_noise_excess, apply-prefix(125.74, "micro")) + +// 2. Visual presentation block +$ + V_("noise","excess") & approx qty(5, "V") times 10^(-15/20) times sqrt(20000) dot 10^-6 \ + V_("noise","excess") & approx qty(5, "V") times 0.1778 times num("141.4e-6") approx qty(125.74, "uV") +$ +`````` + +If you modify a foundational parameter (e.g. system bandwidth or reference +voltages), Typst must re-evaluate all downstream derivations. **If any assertion +fails, the PDF build will halt.** + +## 2. Development Setup + +### Prerequisites + +- **Typst CLI**: Version `0.15.1` or higher. +- **Git:** For version control. + +### Building and Testing + +1. **Clone the repository:** + + ```bash + git clone git@denischevalier.fr:/srv/git/same.git + cd same + ``` + +1. **Run a live watch build:** + + ```bash + typst watch preamble.typ specification.pdf + ``` + + *If your edits break an assertion metrology check anywhere in the 90+ pages, + Typst will throw an immediate compiler error in your terminal.* +2. **Perform a clean release compile:** + + ```bash + typst compile preamble.typ specification.pdf + ``` + +## 3. Structural & Content Guidelines + +### Enumerating Physical Error Sources (Section 4.3) + +When adding a new error mechanism or circuit non-ideality to Section 4.3, you +**must** follow the standard 6-part structure: + +1. **Physical mechanism:** What physical/thermodynamic law causes this error? +2. **Mathematical model:** First-principles equations governing the behavior. +3. **Typical magnitude:** Numerical evaluation using commodity through-hole + component specs. +4. **Where it enters:** Circuit nodes, PCB traces, or mechanical interfaces + vulnerable to this mechanism. +5. **Scaling law:** How the error scales with frequency, temperature, resistance, + bandwidth, or geometry. +6. **Compensation strategy:** Cross-reference to the topological mitigation or + physical layout rules. + +### Vector Graphics & Visual Standards + +- **No Binary Raster Graphics:** Do not commit `.png`, `.jpg`, or bitmap + images for technical drawings, schematics, or plots. +- **CeTZ & CeTZ-Plot:** All mechanical dimensions, panel grids, and mathematical + curves must be written natively using `CeTZ` or `CeTZ-plot` inside `/diagrams` + or `/charts`. +- **Circuits with Zap:** Circuits schematics must be written using `zap` code + directly within the Typst source tree, under `/schematics`. +- **Typographic Consistency:** All text inside vector graphics must use the + document's native typography and unit formatting library (`lib/unify.typ`). + +## 4. Licensing & SPDX Headers + +This project is tri-licensed to properly cover prose, hardware CAD, and +executable code. **Every new file commited to the repository must include the +appropriate SPDX header at line 1: + +```typst +// / SPDX-FileCopyrightText: 2026 Denis Chevalier \ +// / SPDX-License-Identifier: CC-BY-SA-4.0 +// / SPDX-License-Identifier: CERN-OHL-S-2.0+ +// / SPDX-License-Identifier: GPL-3.0-or-later +// +// The prose, explanatory text, rendered figures, tables, and mathematical +// content of this specification are licensed under CC BY-SA 4.0. If a later +// version of CC BY-SA is published, the author grants permission to distribute +// this work under that later version as well. +// +// Hardware designs contained herein (schematics, PCB layouts, mechanical +// drawings, and CAD models) are licensed under CERN-OHL-S-2.0+. +// +// All executable code, helper libraries (`lib/*`), metrology assertions, and +// embedded verification scripts throughout the source documents are licensed +// under the GNU General Public License v3.0 or later (GPL-3.0-or-later). +``` + +## 5. Submitting Pull Requests + +To keep the history clean and maintainable: + +1. **Atomic Commits:** Make small, focused commits. Separate structural Typst + refactoring from mathematical derivations and text revisions. +2. **Verify Local Builds:** Ensure `typst compile preamble.typ` completes with + zero errors and zero warnings before opening a PR. +3. **PR Description Checklist:** + - Explain the engineering rationale behind any parameter changes. + - Cite relevant metrology literature, datasheets, or academic papers if + introducing new concepts. + - Confirm all assertions pass. +4. **Clean Diffs:** Avoid re-formating unrelated `.typ` files. Keep line breaks + logical (semantic line breaks are preferred). + +## Questions or Discussion? + +If you are planning a major structural change to the specification, please send +a mail to [Denis Chevalier](perso@denischevalier.fr) to discuss the +architectural implications before writing code. -- cgit