Cara Nulis README dan Gitignore yang Rapi

Pernah buka repo GitHub yang isinya cuma kode tanpa penjelasan? Rasanya seperti masuk warung tanpa papan nama, tanpa daftar menu, tanpa harga. Kamu bingung ini jualan apa. Sekarang balik posisinya: repo-mu akan dikunjungi orang lain, termasuk perekrut yang menentukan masa depanmu. README adalah papan nama dan daftar menumu. Dan .gitignore adalah gembok gudang yang memastikan kunci brankas tidak ikut terpajang di etalase.

Artikel ini episode ke-7 dari series Git dan GitHub, sekaligus penutup fondasi sebelum kita masuk proyek. Kita bahas dua file kecil yang dampaknya besar: README.md yang menjual proyekmu, dan .gitignore yang menjaganya tetap bersih dan aman.

README Adalah Landing Page Proyekmu

Faktanya pahit tapi perlu didengar: kebanyakan pengunjung repo memutuskan dalam hitungan detik, lanjut baca atau tutup tab. Yang mereka nilai pertama bukan kualitas kodemu, karena mereka belum membacanya. Yang dinilai adalah README. Repo dengan README bagus terlihat dirawat. Repo tanpa README terlihat terbengkalai, sebagus apa pun kodenya.

Struktur README yang terbukti efektif, dari atas ke bawah: judul dan satu kalimat penjelasan tentang apa ini dan buat siapa. Bukti visual kalau memungkinkan, screenshot atau GIF demo singkat. Cara menjalankan cepat, idealnya bisa dicoba dalam lima menit atau kurang. Fitur utama dalam daftar singkat. Cara instalasi dan pemakaian yang langkahnya bisa di-copy-paste. Terakhir lisensi, satu baris cukup, misalnya MIT. Urutan ini bukan aturan sakral, tapi mencerminkan cara orang membaca: apa ini, buktikan, gimana cara pakainya.

Luruskan Dulu: README Bukan Formalitas, Gitignore Bukan Sekadar Node Modules

Salah kaprah pertama: README cuma formalitas, yang penting kodenya jalan. Kode yang jalan tapi tidak bisa dipakai orang lain nilainya turun drastis. Perekrut yang membuka GitHub-mu tidak akan membaca 2000 baris kodemu. Mereka membaca README-mu 30 detik, lalu memutuskan. Tiga puluh detik itu menentukan apakah mereka lanjut atau pindah ke kandidat berikutnya.

Salah kaprah kedua: .gitignore cuma buat ngumpetin node_modules. Fungsi sesungguhnya jauh lebih serius: mencegah file rahasia bocor ke publik. API key, password database, token akses. Sekali ter-commit dan ter-push ke repo publik, anggap rahasia itu sudah bocor selamanya, walau commit-nya dihapus belakangan, karena riwayat Git menyimpan semuanya. Inilah alasan .gitignore harus ada sejak commit pertama, bukan belakangan.

Menulis README yang Bikin Orang Betah

Mari bedah contoh nyata. README yang buruk biasanya begini:

# my-app

Aplikasi saya.

## Cara pakai
Jalankan aja.

Bandingkan dengan versi yang diperbaiki:

# Kalkulator Diskon

Aplikasi web sederhana untuk menghitung harga akhir setelah diskon,
dibuat untuk latihan JavaScript dasar.

## Cara Menjalankan

1. Buka file `index.html` di browser, atau
2. Jalankan `npx serve` lalu buka http://localhost:3000

## Fitur

- Hitung diskon persen dan nominal
- Riwayat perhitungan tersimpan otomatis

## Lisensi

MIT

Perhatikan polanya: kalimat pertama menjelaskan apa dan untuk apa, bukan cuma nama. Cara menjalankan bisa diikuti tanpa menebak-nebak. Tidak ada bagian yang membuat pembaca bertanya "maksudnya gimana?". Prinsipnya sederhana: tulis README untuk orang yang tidak tahu apa-apa tentang proyekmu, karena memang begitu kondisi setiap pengunjung baru.

Sintaks Gitignore: Pola Sederhana yang Powerful

File .gitignore ditaruh di root repo. Setiap baris adalah satu pola. Sintaksnya cuma segenggam, tapi menguasai lima pola ini sudah cukup untuk 95 persen kebutuhan:

# Komentar diawali pagar
*.log            # semua file berakhiran .log, di folder mana pun
.env             # file bernama .env, tempat API key biasanya disimpan
node_modules/    # seluruh folder node_modules beserta isinya
/dist/           # folder dist, tapi hanya yang di root repo
!important.log   # pengecualian: file ini tetap dilacak

Analoginya seperti daftar aturan satpam gedung. *.log berarti "semua orang berkaos log dilarang masuk, di lantai mana pun". /dist/ berarti "larangan khusus untuk ruangan dist di lantai dasar saja". Tanda seru ! adalah surat izin khusus yang mengalahkan larangan umum. Dan ingat aturan mainnya: .gitignore hanya berlaku untuk file yang belum dilacak. Kalau file rahasia sudah terlanjur ter-commit, menambahkannya ke .gitignore tidak akan menghapusnya dari riwayat.

Template Siap Pakai Biar Tidak Mulai dari Nol

Kabar baiknya kamu tidak perlu menghafal pola untuk setiap bahasa. GitHub menyediakan koleksi template .gitignore siap pakai untuk hampir semua bahasa dan framework di github.com/github/gitignore. Untuk proyek web pemula, template Node sudah mencakup node_modules, file log, file .env, dan folder build. Cara pakainya: salin isinya ke file .gitignore-mu, lalu tambahkan baris khusus proyekmu di bawahnya. Jangan lupa commit file .gitignore-nya juga, supaya satu tim otomatis memakai aturan yang sama.

# Dependensi - bisa install ulang, jangan di-commit
node_modules/

# Rahasia - JANGAN PERNAH di-commit
.env
.env.local
config.json

# Hasil build & log - bisa dibuat ulang
/dist/
/build/
*.log

# File sistem & editor
.DS_Store
Thumbs.db
.vscode/

Tiga Kesalahan README yang Paling Sering Ditemui

Setelah tahu strukturnya, hindari tiga kesalahan klasik ini. Pertama, README yang basi. Cara instalasi masih menulis perintah versi lama, screenshot menampilkan tampilan dua tahun lalu. README basi lebih buruk daripada tidak ada README, karena menyesatkan. Setiap kali merilis perubahan besar, sempatkan update README. Jadikan bagian dari definisi "selesai".

Kedua, dinding teks tanpa struktur. Satu paragraf 500 kata tanpa heading, tanpa daftar, tanpa contoh kode. Tidak ada yang membacanya. Pecah jadi section pendek, pakai heading, kasih contoh yang bisa di-copy. Pembaca README itu scanner, bukan pembaca novel.

Ketiga, tidak ada cara menghubungi atau berkontribusi. Pengunjung yang tertarik lalu bingung "terus gimana?" adalah peluang hilang. Satu baris kontak atau link ke panduan kontribusi menutup celah itu. Untuk proyek open source, section Contributing yang jelas sering menjadi pembeda antara proyek yang ramai kontributor dan yang sepi.

Latihan: Rapikan Satu Repo Sampai Layak Dipamerkan

Pilih satu repo latihanmu, yang paling kamu banggakan, dan rapikan sampai layak dibuka perekrut.

1. Tulis ulang README-nya mengikuti struktur: judul plus satu kalimat penjelasan, cara menjalankan yang bisa di-copy-paste, daftar fitur singkat, dan lisensi. Minta satu teman membacanya dan menjalankan proyekmu hanya bermodal README itu. Kalau dia tersendat, bagian itulah yang perlu diperbaiki.
2. Tambahkan file .gitignore dari template di atas, sesuaikan dengan proyekmu. Jalankan git status dan pastikan file sampah tidak lagi muncul.
3. Ubah, bukan sekadar salin: tambahkan satu bagian baru ke README yang belum dibahas di artikel ini, misalnya bagian "Rencana Pengembangan" berisi 3 fitur yang ingin kamu tambah, atau bagian "Teknologi yang Dipakai". README yang hidup menunjukkan proyek yang hidup.
4. Commit dengan pesan yang rapi, misalnya "Rapikan README dan tambah .gitignore", lalu push.

Fondasi Git-mu sekarang lengkap: dari init sampai repo yang rapi dan aman. Saatnya fondasi ini dipakai untuk sesuatu yang terlihat: portofolio online yang bisa dibuka siapa pun. Di episode penutup series ini, Bikin Portofolio Online dengan GitHub Pages, kita deploy websitemu ke internet secara gratis, tanpa sewa hosting sepeser pun.