Paket harus mengikuti Semantic Versioning (SemVer). Versi Semantic adalah strategi yang memungkinkan penulis paket untuk memberikan informasi pada jenis perubahan yang disertakan dalam versi tertentu, dibandingkan dengan versi sebelumnya, dalam format yang alat otomatis dapat digunakan.
Versi Semantic mengekspresikan versi sebagai MAJOR.MINOR.PATCH, di mana MAJOR memperkenalkan satu atau lebih melanggar perubahan, MINOR memperkenalkan satu atau lebih perubahan API yang kompatibel mundur, dan PATCH hanya memperkenalkan perbaikan bug tanpa perubahan API sama sekali.
Ketika Anda mulai mengembangkan paket, mulai jumlah versi pada 0.1.0. Jumlah versi MAJOR 0 disediakan untuk paket dalam fase pengembangan awal mereka. Selama perkembangan awal, paket API berubah sering, seringkali dengan cara yang melanggar, jadi simpan nomor versi MAJOR pada 0 sampai Anda mempertimbangkan paket Anda cukup stabil dan siap digunakan dalam produksi.
Setelah paket secara resmi siap digunakan dalam produksi, meningkatkan versi MAJOR ke 1 dan mematuhi pedoman berikut untuk perubahan berikutnya:
| Increment this value: | Under these conditions: | Example: |
|---|---|---|
| MAJOR | Ada setidaknya satu perubahan putus dan versi paket dapat diganti untuk yang lain. Perubahan putus meliputi: • Mengubah permukaan API (bagian yang terbuka dari API) atau fitur dengan cara yang berisiko atau kesalahan runtime. Login Menghapus fitur non-API, termasuk menghapus Aset atau mengubah GUID Aset. • Menghapus atau mendanai rakitan dan Aset (karena) kompiler mungkin gagal untuk menemukan mereka). NotePATCH dan MINOR ke 0. |
Versi 1.2.3 dan 2.0.0 tidak kompatibel dan tidak dapat digunakan dipertukarkan tanpa risiko. |
| MINOR (same MAJOR value) |
MINOR tertinggi memperkenalkan fungsi dengan cara yang kompatibel ke belakang. Perubahan API yang kompatibel (atau non-breaking) termasuk: • Mengubah permukaan API atau fitur tanpa risiko kompilasi atau kesalahan runtime. • Menambahkan fitur non-API. • Menambahkan rakitan dan Aset (karena barang baru tidak memiliki referensi pre-existing). Note: Ketika meningkatkan versi minor, selalu mengatur versi PATCH ke 0. |
Anda dapat menggunakan Versi 1.3.0 untuk memenuhi ketergantungan pada 1.2.0, karena 1.3.0 kompatibel kembali. Anda tidak dapat menggunakan 1.2.0 untuk memenuhi ketergantungan pada 1.3.0. |
| PATCH (same MAJOR.MINOR nilai) |
PATCH tertinggi memperkenalkan perbaikan bug tanpa mengubah API sama sekali, dengan cara yang kompatibel kembali. API tidak berubah jika: • Permukaan API identik dan fitur tetap tidak berubah. Login Perubahan tidak mengubah API publik. • The changes don’t alter the public API. |
Versi 1.3.0 dan 1.3.1 harus dipertukarkan karena memiliki API yang sama, meskipun 1.3.1 mengandung perbaikan bug tidak hadir dalam 1.3.0. |
Mengikuti praktek-praktek versi ini memungkinkan Manajer Paket untuk secara otomatis menyelesaikan konflik (ketika mungkin), atau meng-upgrade paket ke versi baru, yang kompatibel kembali.
Bagian berikut menjelaskan skenario untuk membantu Anda menentukan bagaimana aturan ini mempengaruhi berbagai elemen paket:
Selain skenario ini, ada faktor lain yang dapat mempengaruhi beberapa perubahan yang biasanya hanya memerlukan peningkatan versi MINOR atau PATCH: apakah properti Auto Referenced diaktifkan atau dinonaktifkan.
Salah satu properti yang dapat Anda set untuk properti definisi perakitan Anda adalah properti Auto Referenced, yang mengontrol apakah Unity secara otomatis merujuk file selama kompilasi. Ketika properti ini diaktifkan, beberapa perubahan yang biasanya hanya membutuhkan peningkatan versi MINOR atau PATCH sekarang menjadi melanggar perubahan.
Ketika Anda disable auto-referencing, jika Anda membuat perubahan yang menghasilkan perakitan baru tersedia, Anda memperkenalkan perubahan yang kompatibel ke API. Perubahan API yang kompatibel kembali, seperti menambahkan platform, menonaktifkan Referensi Uji Unity, menambahkan .asmdef baru, atau menghapus Kontras Define, hanya memerlukan peningkatan MINOR.
Namun, ketika Anda enable auto-referencing, bahwa perakitan baru ditambahkan sangat ditambahkan ke referensi berbagai rakitan lainnya. Karena kasus-kasus tersebut dapat menyebabkan kesalahan kompilasi pada rakitan lain, sehingga membutuhkan peningkatan MAJOR.
Kasus umum lain terjadi ketika Anda menambahkan atau mengubah versi untuk ketergantungan paket. Sebagian besar waktu, mengubah ketergantungan paket hanya membutuhkan peningkatan PATCH. Namun, versi paket baru mungkin mengandung perakitan dengan properti Auto Referenced, yang menjadi perubahan putus, dan oleh karena itu membutuhkan peningkatan enabled.MAJOR increase.
Untuk menghindari masalah seperti ini, selalu mencoba untuk menghindari menempatkan file DLL pihak ketiga ke dalam paket yang tidak terkait (seperti Newtonsoft.Json.dll dalam paket SaveGameManager).
Proyek dapat merujuk setiap aset yang terlihat pada database aset. Aset Database melacak aset ini secara unik menggunakan GUID yang didefinisikan dalam file .meta mereka.
Ketika Anda memperkenalkan salah satu perubahan ini ke API publik, ini membutuhkan rilis MAJOR baru, karena mereka adalah breaking changes:
| Scenario: | Why these are breaking changes: |
|---|---|
| Menghapus Aset yang terlihat ke Basis Data Aset | Jika Anda menghapus Aset, ini mungkin melanggar referensi dalam Proyek pengguna atau paket lainnya. |
| Mengubah GUID dari Aset | Jika Anda mengubah Aset GUID, Aset Database memahami ini sebagai menghapus Aset asli dan kemudian menambahkan Aset (identical) baru. Hasil ini dalam referensi yang rusak, karena GUID asli tidak lagi poin ke Aset, sehingga Aset Database tidak dapat menyelesaikan referensi. |
Definisi perakitan (.asmdef) mendefinisikan sekelompok scriptsSepotong kode yang memungkinkan Anda untuk membuat Komponen Anda sendiri, memicu peristiwa permainan, memodifikasi sifat komponen dari waktu ke waktu dan menanggapi input pengguna dengan cara apa pun yang Anda sukai. More info
Lihat di Glossary yang menjadi pipa kompilasi Unity Editor berubah menjadi rakitan yang dikelola terpisah (.dll). Aset .asmdef ini termasuk sifat yang menggerakkan sifat perakitan yang dihasilkan. Ini termasuk:
Sebagian besar properti memiliki dampak pada konsumen perakitan, sehingga mengubah sifat ini merupakan perubahan pada API publik paket. Properti lain tidak memiliki dampak pada konsumen perakitan, sehingga mengubah salah satu dari ini tidak dianggap mengubah API paket.
Warning: Properti Auto Referenced adalah kasus khusus, karena banyak perubahan yang biasanya tidak mengubah API sama sekali atau akan mengubah API dengan cara yang kompatibel ke belakang dapat menyebabkan kesalahan kompilasi, tergantung pada apakah atau tidak diaktifkan. Untuk informasi lebih lanjut, lihat Automatic referencing.
Unity dapat berupa rakitan pre-compile, atau mengkompilasinya dari skrip dan definisi perakitan. Oleh karena itu, apa pun yang berlaku untuk definisi perakitan umumnya juga berlaku untuk rakitan yang telah ditentukan.
Rincian bagian ini berubah dalam definisi perakitan dan rakitan yang telah ditentukan, dan dampak pada versi paket:
Ketika Anda memperkenalkan breaking change ke API publik, ini membutuhkan rilis MAJOR baru, karena mungkin menyebabkan kompilasi dan kesalahan runtime. skenario ini semua menghilangkan atau menyembunyikan perakitan dari rakitan lain yang merujuk itu. Ketika perakitan menggunakan jenis yang didefinisikan dalam perakitan yang direferensikan, jika kompiler tidak dapat menemukan bahwa perakitan lain, yang menghasilkan kesalahan kompilasi. Untuk informasi lebih lanjut tentang bekerja dengan definisi perakitan dan perakitan, lihat Definisi Perakitan.
Perhatikan bahwa berikut berlaku untuk rakitan run-time dan Editor yang paket konsumsi dan penggunaan. Tidak berlaku untuk menguji rakitan, karena paket tidak biasanya mengkonsumsinya, sehingga tidak bagian dari API paket.
| Scenario: | Why the compiler can’t find the referenced assembly: |
|---|---|
| Menghapus definisi perakitan atau perakitan yang telah ditentukan | Menghapus file definisi perakitan mencegah pipa kompilasi dari menghasilkan perakitan yang sesuai. Note: Pada tahun 2019.1, referensi yang hilang diperbolehkan untuk mendukung "referensi opsional" kasus penggunaan, tetapi renaming perakitan yang perlu dikompilasi definisi perakitan menyebabkan kesalahan kompilasi. Demikian juga, jika kode disusun membutuhkan jenis dari perakitan, renaming yang perakitan dapat menyebabkan kesalahan waktu berjalan seperti TypeLoadException. |
| Mengubah nama perakitan (baik dalam file .asmdef atau mengubah nama file .dll) | Mengubah nama perakitan setara untuk menghapus perakitan dan kemudian menambahkan yang baru dengan nama yang berbeda. Ini berarti Unity mempertimbangkan perakitan asli yang hilang, meskipun API masih mengandung kode perakitan yang sama dengan nama lain. |
| Menambahkan define constraint ke ruang .asmdef% | Jika Anda menambahkan kontratraint, Unity skips membandingkan perakitan setiap kali deftraint tidak terpenuhi. Ini menciptakan kasus di mana perakitan hilang, meskipun sebelumnya tersedia. |
| Menghapus platform | Jika Anda menghapus dukungan untuk platform tertentu, Unity tidak lagi mengimpor perakitan di platform itu, yang setara dengan menghapus perakitan. Anda dapat menghapus platform dengan mengaktifkan salah satu properti ini: • includePlatforms, yang memecahkan kompatibilitas dengan semua platform yang tidak terdaftar • excludePlatforms, yang menambahkan entri ke dalamnya |
| Memindahkan publik API dari satu perakitan ke yang lain | Ketika Anda memindahkan kode yang dapat diakses publik dari Majelis A ke Majelis B, setiap perakitan yang merujuk A tetapi tidak B gagal untuk dikompilasi. Untuk definisi perakitan, jika Anda memindahkan skrip di sekitar, Anda mungkin memindahkan API publik ke perakitan yang berbeda. |
| Mengubah properti Auto Referenced property | Ketika Anda disable properti Auto Referenced, Anda tidak bisa lagi menggunakan API publik perakitan ini tanpa referensi eksplisit: • Untuk rakitan yang telah ditentukan, menonaktifkan properti ini mencegah Unity dari implicitly menambahkan perakitan yang telah ditetapkan sebagai referensi untuk definisi perakitan dan rakitan proyek-kompiled. Login Untuk definisi perakitan, menonaktifkan properti ini mencegah Unity dari implicitly menambahkan perakitan yang dihasilkan sebagai referensi ke rakitan kompiled proyek. enable properti Auto Referenced, berpotensi memperkenalkan konflik dengan perubahan lain ke API, properti, atau ketergantungan. Untuk informasi lebih lanjut, lihat bagian Automatic referencing. |
| Mengaktifkan properti Unity References → Test Assemblies dalam definisi perakitan | Mengaktifkan properti Unity References → Test Assemblies menandai perakitan ini sebagai perakitan pengujian, dan Unity tidak biasanya termasuk dalam membangun (atau mengkompilasinya dalam beberapa kasus). Ketika ini terjadi, setiap perakitan merujuk perakitan yang hilang gagal untuk menemukannya, kecuali itu juga perakitan uji. |
Perubahan berikut adalah backward-compatible, atau non-breaking, perubahan API. skenario ini semua menambahkan perakitan, tidak seperti melanggar perubahan yang menghapus perakitan. Karena menambahkan perakitan meningkatkan permukaan API (bagian terpapar API), dianggap sebagai perubahan API. Namun, tidak ada referensi yang ada, sehingga menambahkan perakitan baru tidak akan mempengaruhi rakitan lain yang dibuat dengan API sebelumnya.
Perubahan yang kompatibel kembali memerlukan setidaknya rilis MINOR baru. Jika Anda termasuk pembaruan lain yang melanggar perubahan, maka ini juga dapat menjadi bagian dari rilis MAJOR baru.
Warning: Perubahan ini hanya kompatibel kembali jika properti Auto Referenced dinonaktifkan. Ketika properti Auto Referenced diaktifkan, perubahan yang tercantum dalam tabel ini mungkin menyebabkan perubahan melanggar. Untuk informasi lebih lanjut, lihat bagian Automatic referencing.
| Scenario | Why these changes don’t break compilation |
|---|---|
| Menghapus define constraint ke .asmdef | Menghapus batasan berarti bahwa pipa kompilasi dan skrip tidak lagi melewatkan perakitan ini. Karena Unity selalu membangun perakitan itu, kompiler selalu dapat menyelesaikan referensi ke dalamnya, terlepas dari apakah atau tidak yang menentukan batasan terpenuhi. |
| Menambahkan platform | Menambahkan platform tidak memiliki efek pada dukungan platform yang ada, sehingga tidak kompatibel. Ini adalah perubahan API karena meningkatkan permukaan API. Anda dapat menambahkan platform dengan memodifikasi properti ini: • Tambahkan entri ke properti includePlatforms. Login Hapus properti sepenuhnya. Ini setara dengan menambahkan semua platform yang belum ada di properti includePlatforms. Login Hapus entri dari properti includePlatforms. • Remove entries from the excludePlatforms property. |
| Creating definisi perakitan dengan skrip baru (tidak sebelumnya di bawah file .asmdef yang berbeda) | Menambahkan perakitan baru meningkatkan permukaan API (bagian terpapar API) tanpa mengubah implementasi yang ada. |
| Sitemap Menonaktifkan properti dalam file definisi perakitanUnity References → Test Assemblies property in assembly definition files | Menonaktifkan properti Unity References → Test Assemblies menandai perakitan ini sebagai perakitan biasa, sehingga Unity tidak lagi memperlakukannya berbeda dari setiap definisi perakitan. Ini adalah perubahan API karena meningkatkan permukaan API. |
Perubahan berikut tidak mempengaruhi API publik dan diperbolehkan dalam rilis PATCH. Perubahan dalam skenario ini tidak mengubah API publik karena tidak mempengaruhi permukaan API (bagian terpapar API) dan tidak mengubah apa pun bagi konsumen lain.
Perubahan yang tidak mengubah API publik setidaknya memerlukan rilis PATCH baru. Jika Anda termasuk pembaruan lain yang memperkenalkan perubahan yang melanggar atau tidak melanggar, maka Anda juga dapat menyertakannya dalam rilis MAJOR atau MINOR.
| Scenario | Why these changes don’t impact other consumers |
|---|---|
| Mengubah daftar rakitan dan definisi perakitan yang direferensikan dalam file .asmdef files | Perakitan yang merujuk perakitan lain tidak secara otomatis merujuk bahwa referensi sendiri perakitan lainnya, tetapi harus secara eksplisit daftar mereka. Oleh karena itu, mengubah referensi dalam definisi perakitan atau perakitan tidak mempengaruhi konsumen lain. |
| Mengubah properti Allow unsafe code dalam definisi perakitan | Properti ini mengontrol apakah kompilator diperbolehkan untuk mengkompilasi kode yang memiliki pengubah unsafe. Mengubah bendera sendiri tidak mengubah API publik. |
| Mengubah properti Override References dalam definisi perakitan | Properti ini mengontrol bagaimana menyatukan kompilator untuk perakitan ini, dan tidak berpengaruh pada konsumen perakitan yang dihasilkan. Mengubah bendera sendiri tidak mengubah API publik. |
File paket manifestSetiap paket memiliki manifest, yang menyediakan informasi tentang paket ke Manajer Paket. Manifest mengandung informasi seperti nama paket, versinya, deskripsi untuk pengguna, ketergantungan pada paket lain (jika ada), dan rincian lainnya. More info
Lihat di Glossary (package.json) menentukan nama, versi, ketergantungan paket, dan metadata lainnya tentang paket itu sendiri.
Rincian bagian ini berubah dalam file manifestasi paket, dan dampak pada versi paket:
Mengubah properti name adalah setara dengan menghapus satu paket dan menambahkan paket baru dengan nama yang berbeda, dan tidak didukung. Anda tidak dapat mengubah nama paket dengan mencoba untuk melepaskan pembaruan: Anda harus melepaskannya sebagai paket yang sama sekali baru. Perubahan nama tidak diperbolehkan karena proyek dan paket yang ada tidak dapat menafsirkan nama sebagai sinonim.
Mengubah ketergantungan dalam proyek tidak sendiri memerlukan versi MAJOR atau MINOR yang berbeda, kecuali bagian dari perubahan API atau jika properti Auto Referenced diaktifkan.
Bagian ini memberikan contoh perubahan ketergantungan dan konteks di mana mereka menerapkan (asumsi bahwa properti Auto Referenced dinonaktifkan dan tidak ada perubahan API selain apa yang dijelaskan setiap kasus):
| Dependency change | Context | Minimum version change |
|---|---|---|
| Menambahkan ketergantungan baru | Sitemap Menggunakan paket baru tanpa mengubah perilaku fungsional, dan tidak mengubah permukaan API. | PATCH |
| Sitemap Menggunakan paket baru untuk memperkenalkan perilaku baru, tanpa memodifikasi permukaan API. Login Buat API baru yang mengekspos jenis yang didefinisikan dalam paket baru. • Creates new APIs that expose types defined in the new package. |
MINOR | |
| Sitemap Menggunakan paket baru untuk mengubah perilaku yang ada dengan cara yang tidak dapat diubah kembali, tanpa memodifikasi permukaan API. Login Modifikasi API yang sudah ada dengan cara yang tidak dapat dibalikkan untuk mengekspos jenis yang didefinisikan dalam paket baru. • Modifies existing APIs in a way that is not backwards-compatible to expose types defined in the new package. |
MAJOR | |
| Menghapus ketergantungan | Sitemap Hapus paket tanpa mengubah perilaku fungsional, dan tidak mengubah permukaan API. | PATCH |
| Sitemap Menghapus hasil paket dalam perubahan perilaku yang ada dengan cara yang tidak dapat diubah, tanpa mengubah permukaan API. Login Hapus API yang mengekspos jenis yang didefinisikan dalam ketergantungan itu. • Removes APIs that expose types defined in that dependency. |
MAJOR | |
| Mengubah ketergantungan | Sitemap Menggunakan paket yang dimodifikasi tanpa mengubah perilaku fungsional, dan tidak mengubah permukaan API. | PATCH |
| Sitemap Menggunakan paket yang dimodifikasi untuk memperkenalkan perilaku baru, tanpa memodifikasi permukaan API. Login Buat API baru yang mengekspos jenis yang didefinisikan dalam paket yang dimodifikasi. • Creates new APIs that expose types defined in the modified package. |
MINOR | |
| Sitemap Menggunakan paket yang dimodifikasi untuk mengubah perilaku yang ada dengan cara yang tidak dapat diubah kembali, tanpa memodifikasi permukaan API. Login Mengubah API yang ada dengan cara yang tidak dapat dibalikkan untuk mengekspos jenis yang didefinisikan dalam paket yang dimodifikasi. Login Mengekspos beberapa jenis di API yang berubah dengan cara yang tidak kompatibel dalam paket yang dimodifikasi. Login Mengekspos beberapa jenis di API yang tidak lagi didefinisikan dalam paket yang dimodifikasi. • Changes existing APIs in a way that is not backwards-compatible to expose types defined in the modified package. • Exposes some types in APIs that are changed in a non-backward-compatible way in the modified package. • Exposes some types in APIs that are no longer defined in the modified package. |
MAJOR |
Anda dapat mengubah atribut paket manifest yang tidak memiliki efek khusus pada Manajer Paket, membangun pipa, pipa skrip atau Database Aset dalam versi rilis apa pun. Ini termasuk mengubah description, category, keywords, atau displayName.
Jika Anda mengubah bidang ini, yang mungkin menunjukkan bahwa perubahan Anda melibatkan lebih dari sekadar perbaikan bug. Selalu mempertimbangkan apakah perubahan lain dalam versi baru benar-benar mandat rilis MINOR baru atau MAJOR daripada rilis PATCH.
Note: Perubahan sifat unity atau unityRelease dalam manifestasi paket selalu membutuhkan rilis MINOR atau MAJOR. Meskipun sifat tidak mempengaruhi API paket itu sendiri, meningkatkan versi Unity tidak termasuk versi paket dari bekerja pada editor Unity sebelumnya dan mungkin memecahkan proyek atau paket yang tergantung. Mengurangi versi Unity membuat paket yang tersedia untuk editor Unity yang lebih tua.
Ketika Anda ingin menghapus beberapa fungsi dari API Anda, rilis pertama setidaknya satu versi MINOR yang mengandung deprecation. Ini memperingatkan pengguna tentang penghapusan pengakhiran, sehingga mereka dapat transisi ke API baru dengan lancar. Kemudian Anda dapat menghapus fungsi dalam rilis MAJOR baru.
Jika pengembang lain menandai paket yang usang dengan peringatan dan Anda mengaktifkan Warnings as Errors dalam proyek Anda, paket usang mungkin secara teknis memecah proyek Anda, meskipun itu bukan istirahat sejati karena kode masih berfungsi seperti sebelumnya.
Dalam hal ini, Anda dapat memilih bagaimana Anda ingin memperbaiki peringatan-as-error (dalam urutan turun dari desirabilitas khas):
#pragma warning untuk menyinggung peringatan.