Sebuah proyek belum benar-benar dapat dijalankan ulang jika hanya bekerja pada komputer orang yang membuatnya. Repositori juga perlu mencatat versi alat, dependensi, konfigurasi yang dibutuhkan, dan cara memeriksa bahwa pemasangan berhasil.

Tujuannya bukan membuat semua komputer identik. Tujuannya mengurangi keadaan tersembunyi: hal-hal yang ada di satu mesin, tetapi tidak tertulis di proyek.

Pin versi runtime

Perubahan versi Node.js, Ruby, Python, atau runtime lain dapat mengubah perilaku proyek. Catat versi yang digunakan dalam format yang dibaca alat tim. Proyek Node.js, misalnya, dapat memakai .nvmrc untuk pengelola versi dan engines untuk menyatakan rentang yang didukung.

.nvmrc
24
package.json
{
  "engines": {
    "node": ">=24 <25"
  }
}

Versi runtime dan rentang dukungan menjawab dua pertanyaan berbeda. Berkas versi menyatakan lingkungan yang dipakai tim; engines menyatakan lingkungan yang boleh menjalankan paket tersebut.

Catat pengelola paket

Dua orang dapat memakai Node.js yang sama tetapi menghasilkan pohon dependensi berbeda jika pengelola paket atau lockfile-nya berbeda. Field packageManager di package.json mencatat nama dan versi alat yang dipakai proyek.

package.json
{
  "packageManager": "pnpm@10.33.0"
}

Commit lockfile bersama perubahan dependensi. Jangan membuat lockfile baru dengan alat lain hanya karena alat tersebut sudah terpasang secara global.

Untuk instalasi otomatis, gunakan mode yang menolak perubahan lockfile. Pada pnpm perintahnya:

pnpm install --frozen-lockfile

Kegagalan di sini berguna. Itu menandakan manifest dan lockfile tidak lagi menggambarkan keadaan yang sama.

Pisahkan konfigurasi dari rahasia

Daftar nama variabel lingkungan yang dibutuhkan tanpa memasukkan nilainya ke Git. Berkas .env.example dapat menjadi kontrak sederhana:

.env.example
API_BASE_URL=
EMAIL_FROM=

Jelaskan format dan sumber setiap nilai di dokumentasi. Jika aplikasi bisa memeriksa variabel saat mulai, lakukan pemeriksaan itu dan berikan pesan error yang menyebut nama variabel yang hilang.

Jangan menaruh token sungguhan di contoh. Riwayat Git tetap menyimpan nilai yang sudah dihapus dari commit terbaru.

Sediakan satu jalur pemasangan

README yang baik tidak perlu menjelaskan semua variasi komputer. Ia perlu memberikan satu jalur yang telah diuji:

pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm dev

Pisahkan perintah persiapan, pemeriksaan, pengujian, dan menjalankan aplikasi. Ketika satu langkah gagal, orang yang memasang proyek tahu bagian mana yang perlu diperiksa.

Jika proyek membutuhkan layanan lain, nyatakan namanya, versi minimumnya, port, dan cara mengetahui layanan tersebut siap. Kalimat “jalankan database” belum cukup jika ada beberapa versi dan metode pemasangan yang mungkin.

Verifikasi di lingkungan yang bersih

Dokumentasi setup sering terlihat benar karena penulisnya menjalankan perintah di komputer yang sudah memiliki cache, berkas konfigurasi, dan alat global. Uji dari clone baru atau lingkungan CI yang bersih.

Pemeriksaan minimum:

  1. instalasi selesai hanya dari berkas yang ada di repositori;
  2. build dan test tidak membutuhkan berkas lokal yang terlupakan;
  3. aplikasi gagal dengan pesan yang jelas ketika konfigurasi wajib belum ada;
  4. perintah dokumentasi sama dengan perintah yang dijalankan CI.

Container dapat membantu, tetapi bukan syarat. Lockfile, versi runtime, contoh konfigurasi, dan jalur verifikasi yang jelas sudah menghapus banyak sumber perbedaan tanpa menambah lapisan baru.

Ringkasnya

Lingkungan yang bisa diulang adalah kumpulan keputusan yang dicatat bersama kode. Pin runtime, nyatakan pengelola paket, commit lockfile, dokumentasikan konfigurasi, dan uji jalur pemasangan dari keadaan bersih.

Prinsip yang sama berlaku pada operasi lain. Dalam pengiriman email dari domain baru, konfigurasi dan pemantauan juga perlu dapat dijelaskan dan diulang. Artikel lain dapat ditemukan pada topik Alur Kerja.

Rujukan: Node.js package.json fields, npm package.json, dan pnpm continuous integration.