Kompatibilitas: apa yang dijanjikan sebuah rilis
Peningkatan versi Aggrega dapat mengubah beberapa permukaan yang Anda gunakan sebagai landasan: skema yang menjadi acuan penulisan dokumen Anda, perintah dan flag yang dipanggil skrip Anda, alat yang dipanggil asisten AI, kode galat yang Anda catat, dan kit plugin yang digunakan untuk membangun plugin. Halaman ini menyatakan, untuk masing-masing, apa yang boleh diubah oleh sebuah rilis dan apa yang tidak. Permukaan yang tidak disebut di halaman ini tidak membawa janji apa pun di luar apa yang dinyatakan halaman referensinya sendiri. Bagian terakhir menyebutkan di mana sebuah rilis memberi tahu Anda bahwa salah satunya berubah. Janji di halaman ini berlaku mulai versi 0.9.0. Releases sebelum versi 0.9.0 tidak didukung: registri hub, hub.aggrega.ai, tidak menyediakan versi Plugin apa pun yang dibuat untuk rilis tersebut, dan kompiler rilis tersebut tidak dapat membaca katalog registri itu, yang dokumennya mendeklarasikan aggrega.ai/v1beta1.
Aggrega dirilis sebagai versi 0.x.y: rilis patch menaikkan angka terakhir, rilis minor menaikkan angka tengah. metadata.version milik entitas katalog itu sendiri adalah persoalan terpisah — penulisnya yang memilih, mengikuti kriteria kenaikan versi yang diperiksa oleh aggrega lint --pre-publish, dan Resolusi versi menjelaskan bagaimana sebuah referensi memilih salah satunya.
Skema
Setiap skema yang diterbitkan Aggrega termasuk dalam satu versi API, aggrega.ai/v1beta1 — nilai yang dideklarasikan sebuah dokumen entitas dalam apiVersion-nya. Aturan di bawah ini berlaku untuk masing-masing: jenis entitas, payload plugin, serta skema ruang kerja dan skema lainnya — IR, konfigurasi ruang kerja, lockfile, dan sisanya — semuanya tercantum dalam Referensi skema. Versi API terpisah dari nomor rilis: banyak rilis membaca versi API yang sama.
Apa yang boleh berubah dalam v1beta1
Dalam satu versi API, sebuah skema hanya berubah secara aditif, seperti cara Kubernetes mengubah versi API-nya sendiri. Sebuah rilis boleh:
- mengubah deskripsi;
- menambahkan bidang, bila bidang tersebut opsional.
Setiap dokumen yang valid sebelum perubahan semacam itu tetap valid sesudahnya, dan maknanya tetap sama. Program yang membaca dokumen yang ditulis oleh kompiler, seperti IR atau lockfile, perlu menerima bidang yang tidak dikenalnya, karena bidang opsional yang ditambahkan dapat muncul dalam keluaran tersebut di dalam v1beta1.
Apa yang memerlukan v1beta2
Setiap perubahan berikut memerlukan versi API baru, aggrega.ai/v1beta2:
- menghapus atau mengganti nama bidang;
- menjadikan bidang wajib;
- mempersempit tipe, atau himpunan nilai yang diterima sebuah bidang;
- mengubah makna sebuah nilai.
Versi API baru adalah perubahan yang merusak kompatibilitas, yang dijadwalkan dan diumumkan sebagai perubahan semacam itu dalam rilis yang membawanya.
Bidang opsional baru mencapai katalog bersama kompiler yang mengenalnya
Kompiler menolak bidang yang tidak dideklarasikan skemanya. Ketegasan inilah yang menangkap kunci yang salah eja, dan ketegasan ini memiliki satu konsekuensi yang tidak akan diduga pembaca: entitas katalog boleh mulai menggunakan bidang opsional yang baru ditambahkan hanya dalam rilis yang menyertakan kompiler yang mengenal bidang tersebut.
Sebagai contoh, misalkan sebuah rilis menambahkan bidang opsional ke skema Component — sebut saja spec.newField:
- Setiap Component yang ditulis sebelum rilis itu tetap valid; tidak ada satu pun yang menetapkan bidang tersebut.
- Seorang penulis katalog menerbitkan versi baru sebuah Component yang menetapkan
spec.newField. - Kompiler dari rilis itu, atau rilis yang lebih baru, memvalidasi dan membangun Component tersebut.
- Kompiler dari rilis yang lebih lama menolaknya, karena skemanya sendiri tidak mendeklarasikan bidang tersebut: validasi melaporkan
spec.newField: unexpected propertydan menyebutkan barisnya.
Jadi, siapa pun yang membangun terhadap versi katalog itu terlebih dahulu meningkatkan ke rilis yang menambahkan bidang tersebut, dan katalog menerbitkan entitas yang menggunakan bidang itu hanya setelah rilis tersebut keluar. Cara Release yang terkunci mempertahankan versi yang telah diresolusinya dijelaskan dalam Resolusi versi.
Baris perintah dan alat asisten
Skrip, pipeline CI, dan konfigurasi asisten memanggil perintah aggrega, flag, dan alat asisten berdasarkan namanya. Dalam rilis 0.x:
- Rilis patch tidak pernah menghapus atau mengganti nama perintah, flag, atau alat asisten.
- Rilis minor boleh menghapus atau mengganti nama salah satunya, dan catatan perubahannya menyatakan hal itu di bawah Removed atau Changed.
- Penambahan — perintah, flag, atau alat baru — dapat hadir dalam rilis apa pun.
Alat asisten adalah alat yang ditawarkan aggrega mcp kepada asisten yang terhubung. Daftar lengkapnya adalah jawaban server itu sendiri, dan Apa yang dapat dilakukan asisten Anda dengan Aggrega menjelaskan cara memintanya. Alat yang menjalankan sebuah perintah mengambil namanya dari jalur pemanggilan perintah tersebut, sehingga mengganti nama perintah juga mengganti nama alatnya. Ikhtisar CLI mencantumkan setiap perintah.
Kode galat
Setiap kondisi penghentian membawa kode pendek — huruf E dan empat digit, seperti pada [DEVELOPER_ERROR E0007] — yang dicetak di awal diagnostiknya. Kode pendek adalah kontrak publik: sebuah kode diberikan satu kali, tidak pernah dinomori ulang, dan tidak pernah diberikan kepada kondisi lain. Kode kondisi yang telah dipensiunkan tetap dipensiunkan, sehingga kode yang dicatat dalam runbook, aturan CI, atau issue menunjuk kondisi yang sama setelah setiap peningkatan versi.
Sentinel galat menjelaskan pengenal yang dibawa sebuah kondisi — kode pendek yang dikutip seseorang, kode deskriptif yang dicatat program, dan aksesor Go yang dicocokkan program — apa yang dijanjikan masing-masing, dan bagaimana nomor yang dipensiunkan dicegah agar tidak diberikan lagi. Tabel semua kondisi di halaman itu menguraikan setiap kode pendek, termasuk yang telah dipensiunkan, dan aggrega explain menguraikan satu kode di terminal.
Kit Plugin
Kit pengembangan plugin — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust, dan @aggrega-ai/aggrega-pdk-typescript — serta codec aggrega-abi yang diekspor ulang olehnya mengikuti pemversian semantik mulai dari 0.9.0. Ketiga bahasa kit berbagi satu nomor versi, dan ketiga bahasa codec berbagi nomor versi yang lain.
- Sebuah plugin yang dibangun terhadap suatu versi tetap dapat dibangun terhadap setiap rilis berikutnya pada lini yang sama. Dalam
0.9.x, sebuah rilis boleh menambahkan fungsi, tipe, dan konstanta yang diekspor, dan tidak pernah menghapus atau mengubah satu pun. - Perubahan yang merusak kompatibilitas pada API yang diekspor hanya dirilis dalam versi minor baru (
0.9.xke0.10.0), dan rilis patch tidak pernah merusak kompatibilitas. Kit dan codec beralih ke1.0.0bersamaan dengan1.0.0milik Aggrega sendiri, setelah itu perubahan yang merusak kompatibilitas menaikkan nomor mayor. - Perubahan yang merusak kompatibilitas pada codec adalah perubahan yang merusak kompatibilitas pada kit, yang ikut menaikkan versi minornya sendiri, karena kit mengekspor ulang tipe codec.
- Apakah bidang atau anggota yang ditambahkan ke tipe yang sudah ada dihitung sebagai penambahan bergantung pada bahasanya. README setiap kit, yang diterbitkan bersama paketnya, menyatakan kasus bahasanya di bawah “Compatibility”.
Janji ini mencakup API yang dirujuk oleh kode sumber plugin. Apa yang melintas antara kompiler dan plugin yang sedang berjalan justru dijaga oleh versi ABI plugin: dalam satu versi ABI, sebuah soket hanya mendapat tambahan deskripsi dan bidang opsional, sehingga plugin yang dibangun terhadapnya tetap dapat dimuat. Kontrak plugin menjelaskan soket-soketnya, dan panduan pengembang plugin menjelaskan alur kerja di sekitarnya.
Apa yang dinyatakan catatan perubahan sebuah rilis
Catatan setiap rilis, di halaman rilis, memuat catatan perubahannya, yang dikelompokkan di bawah judul seperti Added, Changed, Removed, dan Fixed. Untuk permukaan di halaman ini:
- Perintah, flag, atau alat asisten yang dihapus atau diganti namanya dicantumkan di bawah Removed atau Changed, dalam rilis minor yang membuat perubahan tersebut.
- Versi API skema yang baru diumumkan sebagai perubahan yang merusak kompatibilitas dalam rilis yang membawanya.
- Perubahan yang merusak kompatibilitas pada kit plugin atau codec terlihat dari nomor versinya: berupa versi minor baru di bawah
1.0.0. - Kode galat tidak pernah berubah makna, sehingga tidak ada rilis yang perlu mengumumkannya.