@@ -18,3 +18,29 @@ Both DSLs live inside `crates/hm-dsl-engine/` so they ship with the crate:
1818
1919- ` crates/hm-dsl-engine/harmont-py/ ` — the ` harmont ` Python package (pipeline DSL).
2020- ` crates/hm-dsl-engine/harmont-ts/ ` — the ` harmont ` TypeScript package (pipeline DSL).
21+
22+ ## Keep the SDK, ` hm init ` templates, and docs in sync
23+
24+ The toolchain helpers in ` crates/hm-dsl-engine/ ` (e.g.
25+ ` harmont-py/harmont/_rust.py ` , ` harmont-ts/src/toolchains/rust.ts ` ) are the
26+ ** public authoring SDK** . They have two downstream surfaces that drift silently
27+ unless you update them in the same change. ** A toolchain change is not done until
28+ all three agree:**
29+
30+ 1 . ** ` hm init ` templates** — ` crates/hm/src/commands/init_templates/<lang>.py ` ,
31+ embedded into the binary via ` include_str! ` in ` crates/hm/src/commands/init.rs ` .
32+ When you change a toolchain's recommended entrypoint (e.g. Rust →
33+ ` rust.project().ci() ` ), update the matching template so scaffolded projects use
34+ the current API. Roundtrip tests: ` crates/hm/tests/cmd_init.rs ` .
35+
36+ 2 . ** Pipeline-SDK reference docs** —
37+ ` docs-site/content/docs/pipeline-sdk/reference/toolchains/<lang>.mdx ` are
38+ ** auto-generated from the Python docstrings** in ` harmont-py ` (griffe →
39+ ` docs-site/scripts/extract-dsl-api.py ` → ` generate-dsl-docs.ts ` ); they carry a
40+ "do not edit" header. So: (a) write/refresh the docstring on any method you add
41+ or change, then (b) regenerate from the simci repo root with ` make docs-generate `
42+ (DSL-only: rebuild ` docs-site/dsl-api.json ` from ` harmont-py ` , then
43+ ` cd docs-site && npx tsx scripts/generate-dsl-docs.ts && npx tsx scripts/check-dsl-pages.ts ` ),
44+ and (c) commit the regenerated ` *.mdx ` in the ** simci (parent) repo** alongside
45+ the gitlink bump. ` check-dsl-pages.ts ` guards that the committed pages match the
46+ docstrings.
0 commit comments