Publikasi dan versioning

Package yang sudah selesai dikembangkan dapat dibagikan ke seluruh ekosistem Dart melalui pub.dev. Topik ini membahas aturan penomoran versi yang diikuti pub, berkas yang wajib disiapkan sebelum package diunggah, pengujian publikasi dengan dart pub publish --dry-run, serta alur perintah dart pub publish yang sesungguhnya. Seluruh contoh dijalankan dengan Dart SDK 3.13 pada package bernama konversi_satuan, sehingga setiap keluaran pada topik ini dapat direproduksi ulang.

Semantic versioning pada package Dart#

Setiap package yang dipublikasikan membawa nomor versi yang dinyatakan pada kunci version di pubspec.yaml. Pub menuntut nomor versi mengikuti format semantic versioning, yakni tiga komponen yang dipisahkan tanda titik pada pola major.minor.patch, contohnya 1.0.0. Komponen major dinaikkan ketika perubahan membuat kode pemanggil sebelumnya tidak kompatibel, komponen minor dinaikkan ketika fitur baru ditambahkan tanpa merusak pemanggil yang sudah ada, sedangkan komponen patch dinaikkan untuk perbaikan bug yang tidak menyentuh API publik. Aturan yang sama membuat batasan versi dapat dipercaya, karena sintaks caret, yaitu tanda ^ di depan nomor versi, bermakna seluruh versi sejak 1.0.0 sampai sebelum 2.0.0.

Keputusan tentang angka mana yang dinaikkan cukup dipandu oleh jenis perubahan yang siap dirilis. Tabel berikut merangkum keputusan tersebut untuk tiga jenis perubahan yang umum terjadi.

Sebelum rilis stabil, package dapat dipublikasikan sebagai prerelease, yaitu nomor versi stabil yang diberi akhiran seperti -dev.1 atau -beta.7, contohnya 1.1.0-dev.1. Versi prerelease selalu lebih rendah daripada versi stabilnya, sehingga ketika 1.1.0 dirilis, versi tersebut mengambil tempat seluruh prerelease 1.1.0-xxx. pub.dev menampilkan tautan prerelease pada halaman package tanpa menggantikan README, dokumentasi, dan skor analisis, serta prerelease tidak muncul pada hasil pencarian. pub memilih versi stabil ketika tersedia, sehingga pemanggil yang ingin menguji prerelease menuliskan akhiran tersebut pada batasan versinya, misalnya ^1.1.0-dev.1.

Konvensi komunitas juga mengatur rentang di bawah 1.0.0. Spesifikasi semantic versioning tidak menjanjikan kompatibilitas apa pun di bawah 1.0.0, tetapi komunitas Dart menggeser makna satu tingkat pada rentang tersebut, yaitu kenaikan dari 0.1.2 ke 0.2.0 menandakan perubahan yang tidak kompatibel, kenaikan ke 0.1.3 menandakan fitur baru, dan kenaikan ke 0.1.2+1 menandakan perubahan yang tidak menyentuh API publik. Sufiks build seperti +1 sebaiknya tidak digunakan lagi setelah package mencapai 1.0.0. Dengan mengikuti konvensi ini, nomor versi memberi janji yang konsisten bagi pembaca halaman package maupun bagi pub saat menyelesaikan batasan versi.

Berkas wajib sebelum publikasi#

Halaman package di pub.dev tidak disusun dari data yang diketik ulang pada situs, melainkan dari berkas yang dibawa package itu sendiri. Kunci description, version, dan repository pada pubspec.yaml mengisi deskripsi, nomor versi, dan tautan halaman repository di sisi halaman package. Dokumentasi publikasi menyarankan deskripsi yang berisi 60 sampai 180 karakter serta tetap menyertakan kunci repository atau homepage agar pembaca mengetahui asal package. Deskripsi ditulis sebagai teks polos tanpa Markdown maupun HTML.

LICENSE adalah satu-satunya berkas yang ditetapkan wajib oleh dokumentasi publikasi. Dokumentasi resmi merekomendasikan lisensi BSD 3-klausa yang biasa digunakan tim Dart dan Flutter, tetapi lisensi lain tetap sah sesuai sifat package-nya. Pengunggah bertanggung jawab memastikan hak untuk menyebarkan setiap berkas yang diunggah. Ukuran package dibatasi pula, dengan rekomendasi kurang dari 100 MB setelah kompresi gzip.

README.md menjadi isi utama halaman package karena di-render dengan Markdown, sedangkan CHANGELOG.md mengisi tab tersendiri yang memuat riwayat perubahan per versi. Setiap nomor versi baru sebaiknya disertai entri baru pada CHANGELOG.md sehingga pembaca halaman package mengetahui apa yang berubah. Saat pengunggahan, pub memasukkan seluruh berkas di bawah akar package, kecuali berkas tersembunyi yang berawalan titik dan berkas yang tercatat pada .gitignore atau .pubignore. Tabel berikut merangkum peran setiap berkas pada publikasi.

Membuat dan menguji package contoh#

Blok berikut membangun package konversi_satuan dari nol di folder ~/contoh/package-dan-pub/publikasi-dan-versioning. pubspec.yaml memuat nama, deskripsi, nomor versi 1.0.0, tautan repository, dan batasan SDK, sedangkan lib/konversi_satuan.dart berisi dua fungsi konversi sederhana. Berkas CHANGELOG.md, LICENSE, dan README.md ditulis sesuai perannya pada tabel sebelumnya, sehingga package memenuhi syarat minimal untuk diuji.

# buat package konversi_satuan dari nol
rm -rf ~/contoh/package-dan-pub/publikasi-dan-versioning
mkdir -p ~/contoh/package-dan-pub/publikasi-dan-versioning/lib
cd ~/contoh/package-dan-pub/publikasi-dan-versioning
cat > pubspec.yaml <<'EOF'
name: konversi_satuan
description: Package Dart untuk konversi satuan panjang dan berat sebagai contoh publikasi.
version: 1.0.0
repository: https://example.com/konversi-satuan
environment:
  sdk: ^3.13.0
EOF
cat > lib/konversi_satuan.dart <<'EOF'
/// Mengubah kilometer menjadi mil.
double kmKeMil(double km) => km * 0.621371;

/// Mengubah kilogram menjadi pon.
double kgKePon(double kg) => kg * 2.2046226;
EOF
cat > CHANGELOG.md <<'EOF'
# Changelog

## 1.0.0

- Rilis awal dengan konversi kilometer ke mil dan kilogram ke pon.
EOF
cat > LICENSE <<'EOF'
MIT License

Copyright (c) 2026 Penulis package konversi_satuan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
EOF
cat > README.md <<'EOF'
# konversi_satuan

Package Dart sederhana untuk konversi satuan panjang dan berat.

## Penggunaan

Tambahkan package sebagai dependensi pada pubspec.yaml, lalu panggil salah
satu fungsi konversinya:

    import 'package:konversi_satuan/konversi_satuan.dart';

    void main() {
      print(kmKeMil(42));
      print(kgKePon(10));
    }

## Lisensi

Package ini dirilis dengan lisensi MIT yang tercantum pada berkas LICENSE.
EOF

Validasi dijalankan dengan perintah dart pub publish --dry-run. Perintah ini memeriksa format pubspec dan konvensi tata letak package, lalu menampilkan seluruh berkas yang akan diunggah tanpa benar-benar mengunggah apa pun. Daftar berkas pada keluaran perlu ditinjau karena berkas yang tidak disengaja ikut terpublikasi bila terlewat.

# uji publikasi tanpa mengunggah apa pun
export PATH=/home/kal/dart-sdk/bin:$PATH
cd ~/contoh/package-dan-pub/publikasi-dan-versioning
dart pub publish --dry-run

Resolving dependencies...
Downloading packages...
Got dependencies!
Publishing konversi_satuan 1.0.0 to https://pub.dev:
├── CHANGELOG.md (<1 KB)
├── LICENSE (1 KB)
├── README.md (<1 KB)
├── lib
│   └── konversi_satuan.dart (<1 KB)
└── pubspec.yaml (<1 KB)

Total compressed archive size: 1 KB.
Validating package...
The server may enforce additional checks.

Package has 0 warnings.

Keluaran di atas terbagi menjadi tiga bagian. Bagian pertama adalah daftar berkas beserta ukurannya yang diakhiri ukuran arsip termampatkan, yaitu 1 KB pada contoh ini. Bagian kedua adalah jalannya validasi yang diakhiri baris The server may enforce additional checks., yaitu pengingat bahwa pub.dev dapat menjalankan pemeriksaan tambahan di sisi server saat pengunggahan sungguhan. Bagian ketiga adalah keputusan validasinya, dan baris Package has 0 warnings. menandakan tidak ada peringatan yang perlu dibereskan. Bila validasi menemukan masalah, berkas yang bersangkutan diperbaiki terlebih dahulu, lalu pengujian diulang sampai keluarannya bersih.

Alur dart pub publish#

Publikasi sesungguhnya dijalankan dengan perintah yang sama tanpa argumen --dry-run. Perintah dart pub publish mengulang verifikasi format dan tata letak, memeriksa status git dan memperingatkan bila berkas terlacak berisi perubahan yang belum di-commit, menampilkan daftar berkas, lalu mengunggah package ke pub.dev. Pengunggahan menuntut kredensial akun Google karena pub menggunakan akun tersebut untuk mengelola izin unggah package. Blok berikut tidak dijalankan karena prosesnya interaktif dan bergantung pada kredensial pemilik akun.

# tidak-dijalankan
# publikasi sungguhan menuntut kredensial akun Google dan konfirmasi interaktif
dart pub publish

Apabila perintah tersebut dijalankan pada terminal milik pengembang, pub menampilkan daftar berkas yang akan diunggah lalu menunggu konfirmasi sebelum arsip dikirim. Pada tahap ini pub meminta masuk ke akun Google untuk membuktikan bahwa akun berhak mengunggah package tersebut. Setelah unggahan berhasil, package langsung dapat dijadikan dependensi dengan menambahkan konversi_satuan: ^1.0.0 pada pubspec.yaml aplikasi yang membutuhkannya. Perintah yang sama digunakan kembali untuk setiap rilis berikutnya, dan nomor versinya diubah lebih dahulu pada pubspec.yaml.

Ringkasan#

• Nomor versi package mengikuti semantic versioning dengan format major.minor.patch, sedangkan prerelease diberi akhiran seperti 1.1.0-dev.1 dan selalu lebih rendah daripada rilis stabilnya.
• pub.dev menyusun halaman package dari README.md, CHANGELOG.md, dan pubspec.yaml, sedangkan LICENSE menjadi satu-satunya berkas yang ditetapkan wajib.
• Perintah dart pub publish --dry-run memvalidasi package dan menampilkan daftar berkas tanpa mengunggah apa pun, sehingga layak dijalankan sebelum setiap rilis.
• Perintah dart pub publish sungguhan menuntut kredensial akun Google dan mengirim versi yang bersifat permanen di pub.dev.

Referensi#

• Publishing packages — dart.dev — Panduan resmi publikasi package beserta berkas wajib, pengujian dry-run, dan penanganan prerelease.
• Package versioning — dart.dev — Penjelasan format versi, sintaks caret, dan cara pub menyelesaikan batasan versi.
• The pubspec file — dart.dev — Referensi kunci pubspec.yaml seperti version, description, dan repository.
• Semantic Versioning 2.0.0 — semver.org — Spesifikasi format major.minor.patch beserta aturan kenaikan angkanya.