Checklist Maintainer — Schema, Rilis & Situs

Empat permukaan yang di-publish FormSpec, dan cara memperbarui masing-masing:

Permukaan	Yang live	Cara update
Rilis CLI — binary formspec	GitHub Releases	§B — make set-version-auto → make release → make release-upload
Website — landing page	formspec.dev	§C — edit site/ → commit → push
Web-docs — dokumentasi	docs.formspec.dev	§D — edit docs/ → commit → push
Schema — JSON Schema registry	schemas.formspec.dev	§A — make publish-schemas → commit → push

Tiga dari empat memakai pemicu yang sama: push ke main. Yang berbeda adalah apa yang harus ikut di-commit sebelum push. Cloudflare Pages auto-build per project dari repo ini (github.com/primadi/formspec), dengan Build watch paths membatasi pemicu per project — lihat ../architecture/09-domain-map.md.

Halaman ini adalah checklist ringkas + penunjuk ke prosedur lengkap. Ia sengaja tidak menduplikasi rincian: sumber kebenaran tetap Makefile, scripts/publish-schemas.sh, scripts/git-push-and-tag.sh, ../../schemas/README.md, ../kind/README.md, dan releasing.md.

---

A. Kalau ada perubahan schema

Kontrak FormSpec punya satu sumber kode: pkg/spec/*.go. Tiga artefak di-generate darinya dan di-commit ke repo — jangan pernah mengedit artefaknya langsung, karena regenerate berikutnya akan menghapusnya.

Artefak	Generator	Konsumen
schemas/formspec.schema.json + schemas/kinds/*.schema.json	make generate-schema	VS Code YAML editor, formspec validate
schemas/dist/<versi>/ (registry)	make publish-schemas	schemas.formspec.dev
docs/kind/<grup>/*.md — tabel Atribut	make generate-kind-docs	docs-site

Urutannya:

1. Ubah sumber, bukan hasil generate. Edit pkg/spec/*.go — struct Go + godoc + annotation // @schema {...} (description, enum, pattern, dll).
2. make generate-schema — regenerasi schemas/ (root + per-kind) dari pkg/spec. Opsional secara eksplisit: langkah 4 memanggilnya juga.
3. make generate-kind-docs — regenerasi tabel Atribut di docs/kind/. Region manual (Kapan Memakai, Contoh Manifest, Gotchas) tidak tersentuh; jangan edit apa pun di antara marker <!-- generated:… -->.
4. make publish-schemas — stage layout versi ke schemas/dist/<versi>/ + alias latest/. Script ini men-generate ulang schema lebih dulu, dan punya guard anti-gitignore (kind baru yang ter-ignore → exit 1).
5. git status --short schemas/dist — pastikan tidak kosong. File kind BARU pernah terlewat senyap karena pola dist/ di .gitignore juga mencocoki schemas/dist/; kini sudah dinegasi (!schemas/dist/) + dijaga guard, tetapi langkah ini tetap jadi jaring pengaman.
6. Tinjau dokumen naratif yang menyebut field/kind yang berubah:
   • docs/spec/… — kontrak normatif (perilaku yang dijanjikan ke user);
   • docs/kind/… — narasi manual per kind (bila kind baru atau peran berubah);
   • docs/reference/ — glossary istilah kanonik;
   • ai_skills/ — skill yang di-embed ke binary lalu ditulis formspec init (manual, bukan generated) — perbarui bila pkg/spec berubah;
   • .github/skills/ — skill agent repo ini, bila menyentuh DX/backend/frontend.
7. Commit bersama dalam satu commit: pkg/spec + schemas/ + docs/kind/ + schemas/dist/ (+ docs manual). Commit message menyebut plan di docs_internal/plan/ yang relevan (workflow discipline).
8. git push — inilah langkah deploy-nya. make publish-schemas hanya men-stage; yang membuat schemas.formspec.dev berubah adalah push ke main (Cloudflare auto-build project formspec-schemas).

Verifikasi:

• go test ./...
• go run ./cmd/formspec validate --spec examples/kafe/spec --schema schemas → 0 problem
• opsional, tanpa push: uji registry-mirror lokal — cd schemas/dist && python3 -m http.server 8791, lalu FORMSPEC_SCHEMA_REGISTRY=http://127.0.0.1:8791 go run ./cmd/formspec validate --spec examples/kafe/spec (hapus cache dulu bila perlu).
• setelah push: curl -I https://schemas.formspec.dev/v1/formspec.schema.json

Rincian registry (layout versi, latest/, konsumsi CLI, opsi R2 cadangan): ../../schemas/README.md. Generator ini deterministik — regenerasi tanpa perubahan pkg/spec menghasilkan diff kosong. Jadi setiap baris yang muncul di schemas/ atau docs/kind/ adalah perubahan nyata, bukan churn; jangan dibuang dengan git checkout.

---

B. Kalau ingin release tag build formspec

Prosedur lengkap (prasyarat, verifikasi artifact, rollback, hapus draft): releasing.md. Yang di bawah ini urutan cepatnya.

Jalur satu perintah — scripts/git-push-and-tag.sh merangkai semuanya: sinkron versi contoh di docs/site → regenerate + commit schema & kind docs → go test → tag + push → make release → make release-upload (draft).

scripts/git-push-and-tag.sh v0.4.2              # semua langkah
scripts/git-push-and-tag.sh v0.4.2 --skip-tests # bila test sudah dijalankan manual

Bertahap — tiga target Makefile, VERSION= tidak perlu diisi di langkah 2–3:

make set-version-auto        # versi + tag di HEAD (PUSH=1 untuk push tag)
make release                 # versi dibaca dari tag yang menunjuk HEAD
make release-upload          # draft di GitHub → review → Publish

Manual, per langkah:

1. git checkout main && git pull origin main — working tree harus bersih; tag harus menunjuk commit yang di-build.
2. Perbarui versi contoh di site/ + docs/ (lihat §B.1 di bawah) — harus masuk commit sebelum tag dibuat, kalau tidak tag menunjuk commit yang masih menampilkan versi lama. scripts/git-push-and-tag.sh melakukannya otomatis; jalur bertahap tidak.
3. go test ./... — harus hijau.
4. Tentukan versi: make set-version-auto (patch-bump dari tag semver tertinggi, guard lengkap, tag dibuat di HEAD), atau eksplisit make set-version-auto VERSION=v0.5.0 untuk bump minor/major. Wajib semver murni (v1.2.3) — bukan string git describe — dan tidak boleh mundur dari tag tertinggi yang sudah ada.
5. Push tag: make set-version-auto PUSH=1 (atau git push origin <tag>). Satu tag = satu release, tidak bisa dipakai ulang.
6. make release — cross-compile 6 target (linux/darwin/windows × amd64/arm64) + packaging → dist/release/.
7. make release-upload — membuat draft release; review lalu klik Publish.
8. Verifikasi pasca-publish: curl -fsSL https://formspec.dev/install.sh | sh && formspec version.

B.1 Versi contoh di site/ + docs/

Dua tempat memuat angka versi hardcoded sebagai contoh (bukan di-resolve saat runtime), jadi keduanya harus ikut ter-commit di rilis:

File	Isi
site/src/components/Install.tsx	preview output formspec version
docs/guides/install.md	contoh --version / FORMSPEC_VERSION

Installer (site/public/install.sh, install.ps1) tidak perlu diubah — ia meresolve versi terbaru via GitHub API saat runtime.

# ganti <lama> → <versi baru> di kedua file, lalu commit
sed -i 's/v0\.0\.9/v0\.0\.10/g' site/src/components/Install.tsx docs/guides/install.md
git add site/src/components/Install.tsx docs/guides/install.md
git commit -m "chore: bump contoh versi installer → v0.0.10"

Perubahan ini ikut ter-deploy otomatis: menyentuh site/ → rebuild formspec.dev, menyentuh docs/ → rebuild docs.formspec.dev (§C, §D).

Perhatikan urutannya — commit versi contoh dulu, baru make set-version-auto, supaya tag menunjuk commit yang sudah memuat versi benar. Ini juga alasan scripts/git-push-and-tag.sh melakukannya di langkah 0 (sebelum tag).

Catatan penting:

• make release tidak membuat tag (tag = keputusan sadar maintainer) — make set-version-auto yang melakukannya. Urutan tag ↔ build tidak saling bergantung, asal tag menunjuk commit yang dibangun; make release membaca tag semver yang menunjuk HEAD, jadi hasil set-version-auto langsung dipakai.
• make release-upload idempotent — boleh diulang bila upload terputus. Release yang sudah published ditolak (satu tag = satu release).
• Build SPA + brotli terjadi sekali di build-spa; jangan meng-copy renderers/react-shadcn/dist/ sebelum kompresi selesai.
• GitHub Actions yang men-trigger on tag push belum ada (sengaja ditunda) — lihat releasing.md §"Belum otomatis (deferred)".

---

C. Kalau ingin update website (formspec.dev)

Landing page ada di site/ (Vite + React + Tailwind). Tidak ada langkah staging atau upload: Cloudflare Pages project formspec-site membangun dari sumber saat push ke main menyentuh site/*.

1. Edit site/src/** (section/komponen di site/src/components/).
2. make site-dev — verifikasi lokal di http://localhost:5198/ (make site-dev PORT=5300 untuk port lain).
3. make site-build — typecheck + build produksi ke site/dist/ (make site-typecheck bila hanya ingin typecheck). site/dist/ di-gitignore; ini hanya verifikasi lokal, bukan artefak yang di-deploy.
4. git add site && git commit && git push — inilah deploy-nya.

Verifikasi: curl -I https://formspec.dev → 200.

Catatan:

• Redirect & header statis hidup di site/public/ (_redirects, _headers, .well-known/security.txt) — ikut ter-deploy sebagai aset.
• Redirect www.formspec.dev → apex tidak lewat _redirects (domain redirect tidak didukung) — dikelola sebagai Redirect Rule di dashboard Cloudflare.
• Build watch paths membatasi rebuild: formspec-site hanya dibangun ulang saat push menyentuh site/*, formspec-docs saat docs/* atau docs-site/*. Jadi perubahan docs/ tidak memicu rebuild landing page. Rincian & alternatif (GitHub Actions + Deployment Hook): ../architecture/09-domain-map.md.

D. Kalau ingin update web-docs (docs.formspec.dev)

Dokumentasi publik = isi docs/ di repo ini, dirender VitePress oleh docs-site/. Satu sumber, tanpa salinan: docs-site/docs adalah symlink ke ../docs, jadi cukup edit docs/ — tidak ada langkah sinkronisasi konten.

1. Edit docs/**/*.md (spesifikasi, kind, guides, architecture, dst).
2. make docs-serve — pratinjau lokal di http://localhost:8000/docs/. Alternatif setara dengan tampilan produksi: cd docs-site && npm run dev.
3. git add docs && git commit && git push — inilah deploy-nya.

Verifikasi: curl -I https://docs.formspec.dev → 200.

Catatan:

• Cloudflare Pages project formspec-docs membangun dari root directory docs-site dengan build command npm install && ln -sfn ../docs docs && npm run build. Symlink itu di-gitignore, jadi build command wajib membuatnya ulang — jangan menghapus ln -sfn dari konfigurasi project.
• docs_internal/ tidak ikut ter-publish (ia di luar docs/). Lihat ../README.md untuk aturan apa yang boleh masuk docs/.
• Menambah/memindahkan halaman: perbarui juga indeksnya (docs/README.md, docs/*/README.md) dan tautan relatifnya.
• Bila perubahan docs ikut rilis, docs/guides/install.md juga bagian dari §B.1 (versi contoh hardcoded).

E. Kalau semuanya dalam satu rilis

Perubahan pkg/spec yang ikut ter-rilis harus masuk tag dalam keadaan sudah diregenerasi. Urutan yang benar untuk rilis yang menyentuh banyak permukaan:

1. §A — make generate-schema / generate-kind-docs / publish-schemas, lalu commit pkg/spec + schemas/ + docs/kind/ + schemas/dist/.
2. §B.1 — perbarui versi contoh di site/ + docs/, commit.
3. §B — make set-version-auto → make release → make release-upload.
4. §C / §D — bila ada perubahan landing page atau docs yang belum di-commit, commit lalu push.

Satu git push ke main lalu memicu tiga build Cloudflare (site, docs, schema) sesuai Build watch paths — tidak ada langkah deploy manual untuk ketiganya. Tag + release-upload terpisah: ia tidak membaca push, ia membaca ref/tag dan dist/release/.

Jalur scripts/git-push-and-tag.sh melakukan langkah 1–3 secara otomatis (regenerate + commit di langkah 0.5, versi contoh di langkah 0) sebelum tag dibuat — sehingga tag tidak pernah membawa schema/kind docs atau versi contoh yang basi.

Ringkasan yang mudah diingat

Yang berubah	Perintah
Kontrak pkg/spec	make generate-schema → make generate-kind-docs → make publish-schemas → commit+push
Rilis binary CLI	make set-version-auto → make release → make release-upload
Landing page site/	edit → make site-build (verifikasi) → commit+push
Dokumentasi docs/	edit → make docs-serve (verifikasi) → commit+push

Semua push ke main; semua deploy Cloudflare otomatis; tidak ada perintah wrangler deploy manual di alur normal. wrangler hanya dipakai Cloudflare di sisi build (lihat site/wrangler.toml, docs-site/wrangler.toml, schemas/wrangler.toml).