Code Repository

Nama Repository

Developer sering melihat project lama sebagai referensi saat mengerjakan project baru yang mirip. Karena itu repository harus mudah dicari dari namanya, jelas, dan menjelaskan dirinya sendiri.

Konvensi

• Semua huruf kecil
• Memakai kebab case, dengan tanda hubung (-). Benar: nac-pholivery. Salah: nac_pholivery atau NAC-Pholivery
• Untuk repository project dari klien yang berulang, awali dengan kode singkat nama klien yang sudah dikenal, misalnya bsif untuk Bank Syariah Indonesia Finance, bcad untuk BCA Digital, dan seterusnya. Kode ini harus sama dengan kode klien di CRM.
• Bagian kedua adalah kode nama project yang sudah dikenal. Contoh online-galleries untuk Online Galleries, emeterai untuk aplikasi E-Meterai, dan seterusnya. Sama seperti di atas, ini harus sama dengan kode klien di CRM.
• Bagian berikutnya adalah bagian project yang lebih spesifik. Contoh backend untuk bagian Backend, frontend untuk bagian aplikasi web, mobile untuk aplikasi mobile yang dibuat dengan framework hybrid seperti Flutter atau React Native, android dan ios masing-masing untuk aplikasi mobile native.

Deskripsi Repository

Nama repository terbatas jumlah karakternya (maksimal 40 karakter di Github), jadi deskripsi (atau Project Description di Gitlab) adalah cara terbaik untuk menjelaskan repository secara singkat, dan tetap bisa dicari serta muncul di hasil pencarian.

Konvensi

• Minimal menjelaskan nama repository. Contoh, deskripsi untuk repository bcaf-emeterai-backend minimal ditulis "BCA Finance E-Meterai Backend", supaya kita tahu bcaf itu singkatan dari apa.
• Memuat teknologi atau framework utama yang dipakai. Contoh, "BCA Finance Virtual Mall Backend Using Spring Boot", supaya kita mudah mencari repository berdasarkan framework atau teknologi besar seperti Spring Boot, Laravel, Angular JS, Flutter, dan lainnya.
• Bila perlu, tulis bahasa pemrograman yang dipakai sebagai pembeda. Contoh tulis Kotlin untuk membedakan dengan project lain yang memakai Java, atau tulis Swift untuk membedakan dengan project lain yang memakai Objective C.

README

Sesuai namanya, README adalah dokumen pertama yang diminta untuk dibaca sebelum orang menelusuri file source code. Kebanyakan source control menaruh README sebagai halaman depan repository. README harus menjelaskan isi repository dengan jelas dan mudah diikuti.

Konvensi

• Memuat gambaran umum atau informasi umum tentang project
• Memuat teknologi yang dipakai
• Memuat instruksi setup, terutama setup development untuk developer lain
• Boleh ditambah screenshot atau diagram arsitektur

Nama Branch

Git memberi strategi branching yang fleksibel dan sangat berguna untuk kolaborasi serta otomasi CI/CD. Namun tanpa konvensi penamaan yang tepat, hasilnya membingungkan dan membuat perawatan kode jadi rumit.

Konvensi

Secara umum ada dua jenis branch: Regular & Temporary Branch.

Regular Git Branch

Branch jenis ini ada secara permanen di dalam repository.

• main adalah branch utama dan dipakai untuk production. Branch ini harus selalu stabil dan tidak boleh menerima commit langsung. Perubahan di branch ini HANYA boleh masuk lewat merge dari regular branch lain seperti staging.

• staging berisi seluruh kode untuk QA, user testing, atau automation testing dari semua perubahan yang sudah dikerjakan. Sebelum masuk ke environment production, setiap perubahan wajib melewati branch ini.

• development adalah branch development utama. Di sinilah semua developer berkontribusi ke project, dengan commit langsung atau lewat Pull Request (PR). Cara kedua lebih disarankan.

Kalau memang perlu, boleh ada Git branch tambahan yang disimpan permanen di repository. Contohnya untuk menandai milestone tertentu (misal: sprint), atau environment dan arsitektur yang berbeda (misal: versi OS). Beberapa konvensi yang harus diikuti:

• buat sesingkat mungkin: ubuntu20 bukan for_server_with_ubuntu_version_20
• pakai garis bawah sebagai pemisah: multi_module bukan multi module. Hanya di bagian ini standar memakai garis bawah. Nama repository dan temporary branch memakai tanda hubung
• tanya diri sendiri apakah branch ini memang perlu disimpan permanen, kalau tidak pakai temporary git branch

Temporary Git Branch

Sesuai namanya, branch jenis ini bisa dibuat dan dihapus sesuai kebutuhan. Temporary Git branch juga dipakai developer untuk mengerjakan task tertentu yang diberikan kepadanya, yang nanti di-merge ke branch utama.

Untuk penamaan, pakai format berikut,

group/description

group dipakai untuk mengelompokkan branch berdasarkan tujuannya, yaitu:

• fix untuk Bug Fix Branch: berisi perbaikan bug yang sudah diketahui atau temuan QA
• hotfix untuk Hot Fix Branch: berisi perbaikan mendesak, biasanya perubahan kecil dan langsung untuk memperbaiki masalah di production, karena itu sifatnya mendesak
• feat untuk Feature Branch: fitur baru yang nantinya di-merge ke regular branch
• docs untuk Documentation Branch: berisi perubahan dokumentasi saja, tanpa perubahan kode
• chore untuk Chore Branch: berisi perubahan yang tidak terlihat oleh user luar, misalnya tooling, konfigurasi build, atau perapian repository
• experiment untuk Experimental Branch: berisi kode percobaan dengan library, arsitektur, tools, dan lainnya yang perlu dibagikan ke orang lain
• wip untuk WIP (Work In Progress) Branch: berisi pekerjaan yang belum akan selesai dalam waktu dekat atau perlu dilanjutkan orang lain

Pakai bentuk singkat persis seperti tertulis di atas. Nama group-nya feat, bukan feature, dan fix, bukan bugfix. Branch lama yang dibuat sebelum ini ditetapkan memakai bentuk panjang; biarkan saja, dan mulai sekarang pakai bentuk singkatnya.

description menjelaskan branch dengan konvensi berikut:

• pakai huruf kecil semua: fix/login bukan Fix/Login
• pakai kata benda: feat/ldap-integration bukan feat/integrates-ldap
• pakai tanda hubung (-) sebagai pemisah: wip/payment-gateway bukan wip/payment gateway
• kalau terkait task tertentu di JIRA atau tool project management lain, tulis nomor issue-nya tepat setelah group: feat/PHOL-19-clear-logo, dalam hal ini nomor issue ditulis huruf besar dan itu tidak masalah. Boleh dihilangkan hanya kalau memang tidak ada task-nya
• lihat halaman Git Workflow untuk kapan branch itu dibuat, dibuat dari mana, dan bagaimana nanti di-merge.