Add CONTRIBUTING.md

1 files changed, 158 insertions, 0 deletions

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 \<perso\@denischevalier.fr>
+// / 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.