chore(versioning): define and align package, API, AsyncAPI, and module versions #451

Objective

Tetapkan kebijakan versioning yang jelas untuk package.json, OpenAPI, AsyncAPI, dan module descriptor agar tidak terlihat stale atau konflik dengan status rilis AWCMS-Mini.

Context

package.json sudah berada di versi 0.23.5, sedangkan kontrak OpenAPI/AsyncAPI masih memakai version: 0.1.0, dan beberapa module descriptor masih memakai version: 0.1.0 serta status experimental. Hal ini bisa benar bila contract/module version memang dipisah dari package version, tetapi perlu kebijakan eksplisit dan enforcement minimal.

Related: #450

Assumptions

• API contract version boleh berbeda dari package version bila ada keputusan tertulis.
• Module descriptor bisa punya lifecycle sendiri, tetapi status experimental harus disengaja.
• Tidak semua perubahan versioning harus mengubah perilaku runtime.

Scope

• Audit package.json, CHANGELOG.md, openapi/awcms-mini-public-api.openapi.yaml, asyncapi/awcms-mini-domain-events.asyncapi.yaml, dan src/modules/*/module.ts.
• Putuskan salah satu strategi:
  1. contract/module version mengikuti package version, atau
  2. contract/module version independen dengan aturan bump sendiri.
• Dokumentasikan keputusan di ADR atau dokumen versioning yang relevan.
• Update metadata version/status sesuai keputusan.
• Tambahkan check ringan bila memungkinkan agar drift tidak terjadi tanpa alasan.

Out of Scope

• Tidak mengubah endpoint hanya demi version bump.
• Tidak membuat rilis baru kecuali memang diperlukan oleh Changesets.
• Tidak mengubah migration SQL.

Architecture / Security / Data Impact

• Architecture: memperjelas lifecycle API dan modul base.
• Security: metadata versi yang jelas membantu audit dan incident response.
• Data: tidak ada dampak data runtime.

Implementation Steps

1. Baca README.md, CHANGELOG.md, .changeset/README.md, docs versioning, OpenAPI, AsyncAPI, dan semua src/modules/*/module.ts.
2. Tentukan apakah OpenAPI/AsyncAPI info.version mengikuti SemVer package atau contract SemVer independen.
3. Tentukan status modul: mana yang masih experimental, mana yang layak active.
4. Dokumentasikan keputusan di ADR atau docs versioning.
5. Update file metadata sesuai keputusan.
6. Tambahkan test/check bila sederhana, misalnya script yang memverifikasi kebijakan versioning.

Acceptance Criteria

• Ada kebijakan tertulis untuk hubungan versi package, OpenAPI, AsyncAPI, dan module descriptor.
• OpenAPI/AsyncAPI tidak tampak stale tanpa penjelasan.
• Module descriptor mencerminkan maturity modul saat ini.
• bun run api:spec:check tetap pass.
• bun run check pass atau alasan jelas bila hanya subset test dijalankan.

Testing Checklist

• bun run api:spec:check
• bun run check:docs
• bun run typecheck
• bun run check bila ada perubahan script/check.

Documentation Checklist

• Update ADR atau docs versioning.
• Update README/CHANGELOG bila diperlukan.
• Update OpenAPI/AsyncAPI metadata bila diputuskan.
• Update module descriptor bila diputuskan.

Risks

• Menyamakan semua versi secara mekanis bisa memberi sinyal keliru bahwa semua contract berubah.
• Membiarkan versi independen tanpa dokumen bisa membingungkan konsumen API.

Mitigations

• Dokumentasikan strategi dengan contoh kapan version harus naik.
• Jangan bump contract version bila tidak ada perubahan contract, kecuali kebijakan memang mengikuti package release.

Next Action

Buat audit kecil, pilih kebijakan, update metadata, jalankan spec-check dan docs-check.