Reda Tarzalt
a5ebaf5dd7
Some checks failed
Run Check Script / check (pull_request) Failing after 44s
64 lines
5.0 KiB
HTML
64 lines
5.0 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Harmony Contributor Map</title>
|
|
<style>
|
|
:root { color-scheme: dark; --bg:#101318; --panel:#171b22; --ink:#e8edf3; --muted:#aab4c0; --line:#2a3240; --accent:#8fd3ff; --warn:#ffd28f; }
|
|
body { margin:0; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif; background: radial-gradient(circle at top left, #1d2a3a, var(--bg) 42rem); color:var(--ink); line-height:1.55; }
|
|
main { max-width: 980px; margin: 0 auto; padding: 48px 22px 72px; }
|
|
h1 { font-size: clamp(2rem, 6vw, 4.5rem); line-height:.95; letter-spacing:-.06em; margin:0 0 18px; }
|
|
h2 { margin-top: 34px; letter-spacing:-.03em; }
|
|
a { color: var(--accent); }
|
|
.lede { color:var(--muted); font-size:1.15rem; max-width: 760px; }
|
|
.grid { display:grid; grid-template-columns: repeat(auto-fit, minmax(230px, 1fr)); gap:14px; margin:22px 0; }
|
|
.card, .try { background: color-mix(in srgb, var(--panel), transparent 6%); border:1px solid var(--line); border-radius:18px; padding:18px; box-shadow:0 18px 50px #0005; }
|
|
.card b { display:block; color:#fff; margin-bottom:6px; }
|
|
.path { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; color:#d7ecff; font-size:.92rem; }
|
|
.flow { display:flex; flex-wrap:wrap; gap:10px; align-items:center; margin:18px 0; }
|
|
.pill { border:1px solid var(--line); border-radius:999px; padding:8px 12px; background:#111821; }
|
|
.arrow { color:var(--muted); }
|
|
.try { border-color:#4a3d24; background:#211b12; }
|
|
.try b { color:var(--warn); }
|
|
code { background:#0c1117; border:1px solid var(--line); border-radius:6px; padding:.1rem .35rem; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<main>
|
|
<h1>Harmony Contributor Map</h1>
|
|
<p class="lede">Your first job as a contributor is not to memorize every crate. It is to decide where a change belongs without violating the repo contract in <a href="../AGENTS.md">AGENTS.md</a>.</p>
|
|
|
|
<h2>The Core Loop</h2>
|
|
<div class="flow" aria-label="Score Topology Interpret flow">
|
|
<span class="pill">Score: desired state</span><span class="arrow">→</span>
|
|
<span class="pill">Interpret: execution logic</span><span class="arrow">→</span>
|
|
<span class="pill">Topology: available capabilities</span><span class="arrow">→</span>
|
|
<span class="pill">Outcome: result</span>
|
|
</div>
|
|
<p>Source anchors: <a href="../harmony/src/domain/score.rs"><code>score.rs</code></a>, <a href="../harmony/src/domain/interpret/mod.rs"><code>interpret/mod.rs</code></a>, and <a href="../harmony/src/domain/topology/mod.rs"><code>topology/mod.rs</code></a>. The important contribution rule: a Score declares what it needs through trait bounds, so missing infrastructure support becomes a compile-time problem.</p>
|
|
|
|
<h2>Where Changes Usually Belong</h2>
|
|
<section class="grid">
|
|
<div class="card"><b>New desired infrastructure state</b><span class="path">harmony/src/modules/**</span><br>Create or adjust a Score. Keep operational complexity inside the Score.</div>
|
|
<div class="card"><b>Environment capability</b><span class="path">harmony/src/domain/topology/**</span><br>Add or adjust a capability only if it is an industry concept, not a vendor wrapper.</div>
|
|
<div class="card"><b>Vendor or protocol implementation</b><span class="path">harmony/src/infra/**</span><br>Adapters talk to external systems. The domain should not depend on them.</div>
|
|
<div class="card"><b>App-specific deployment</b><span class="path">*-deploy crates</span><br>ADR-023 says deploy logic for an app lives beside that app, not in core.</div>
|
|
<div class="card"><b>CLI behavior</b><span class="path">harmony_cli</span><br>The CLI should compose Scores; it should not handroll deploy manifests.</div>
|
|
<div class="card"><b>Local Kubernetes runtime</b><span class="path">k3d</span><br>Use when the change is about provisioning or connecting to local K3D.</div>
|
|
</section>
|
|
|
|
<h2>Contribution Red Flags</h2>
|
|
<p>If a test harness, example, or CLI builds raw Kubernetes <code>Deployment</code>, <code>Service</code>, or <code>ConfigMap</code> structs, ADR-023 treats that as a missing Score. If a capability is named after a product, it is probably in the wrong layer. If a helper exists for one call site and makes the code longer, it probably violates the repo contract.</p>
|
|
|
|
<div class="try">
|
|
<b>Try this</b>
|
|
<p>Open <code>harmony/src/modules/helm/chart.rs</code>. Find the Score, its Interpret, and the capability trait bound. Then answer: if Helm command construction changes, should that change live in the Score, the Interpret, or the Topology capability implementation?</p>
|
|
</div>
|
|
|
|
<h2>Primary References</h2>
|
|
<p><a href="../docs/guides/writing-a-score.md">Writing a Score</a>, <a href="../docs/guides/writing-a-topology.md">Writing a Topology</a>, <a href="../docs/guides/adding-capabilities.md">Adding Capabilities</a>, <a href="../docs/adr/002-hexagonal-architecture.md">ADR-002</a>, and <a href="../docs/adr/023-deploy-architecture.md">ADR-023</a>.</p>
|
|
</main>
|
|
</body>
|
|
</html>
|