Membuat README untuk repositori Anda

  • Artikel

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Repositori Git Anda harus memiliki file readme sehingga penonton tahu apa yang dilakukan kode Anda dan bagaimana mereka dapat mulai menggunakannya. Readme Anda harus berbicara dengan audiens berikut:

  • Pengguna yang hanya ingin menjalankan kode Anda.
  • Pengembang yang ingin membangun dan menguji kode Anda. Pengembang juga merupakan pengguna.
  • Kontributor yang ingin mengirimkan perubahan ke kode Anda. Kontributor adalah pengembang dan pengguna.

Tulis readme Anda di Markdown alih-alih teks biasa. Markdown memudahkan untuk memformat teks, menyertakan gambar, dan menautkan sesuai kebutuhan ke lebih banyak dokumentasi dari readme Anda.

Berikut adalah beberapa readme hebat yang menggunakan format ini dan berbicara dengan ketiga audiens, untuk referensi dan inspirasi:

Membuat intro

Mulai readme Anda dengan penjelasan singkat yang menjelaskan proyek Anda. Tambahkan cuplikan layar atau GIF animasi di intro Anda jika proyek Anda memiliki antarmuka pengguna. Jika kode Anda bergantung pada aplikasi atau pustaka lain, pastikan untuk menyatakan dependensi tersebut di intro atau tepat di bawahnya. Aplikasi dan alat yang hanya berjalan pada platform tertentu harus memiliki versi sistem operasi yang didukung yang dicatat di bagian readme ini.

Membantu pengguna Anda memulai

Pandu pengguna melalui mendapatkan kode Anda dan berjalan pada sistem mereka sendiri di bagian berikutnya dari readme Anda. Tetap fokus pada langkah-langkah penting untuk memulai kode Anda. Tautkan ke versi yang diperlukan dari perangkat lunak prasyarat apa pun sehingga pengguna dapat mengaksesnya dengan mudah. Jika Anda memiliki langkah-langkah penyiapan yang kompleks, dokumentasikan langkah-langkah di luar readme Anda dan tautkan ke langkah-langkah tersebut.

Arahkan ke mana mendapatkan rilis terbaru kode Anda. Penginstal biner atau instruksi tentang menggunakan kode Anda melalui alat pengemasan adalah yang terbaik. Jika proyek Anda adalah pustaka atau antarmuka ke API, letakkan cuplikan kode yang menunjukkan penggunaan dasar dan tampilkan output sampel untuk kode dalam cuplikan tersebut.

Menyediakan langkah-langkah build untuk pengembang

Gunakan bagian berikutnya dari readme Anda untuk menunjukkan kepada pengembang cara membangun kode Anda dari kloning baru repositori dan menjalankan pengujian yang disertakan. Lakukan:

  • Berikan detail tentang alat yang diperlukan untuk membangun kode dan dokumentasikan langkah-langkah untuk mengonfigurasinya untuk mendapatkan build yang bersih.
  • Pecahkan instruksi build yang padat atau kompleks ke halaman terpisah dalam dokumentasi Anda dan tautkan jika diperlukan.
  • Jalankan melalui instruksi saat Anda menulisnya untuk memverifikasi instruksi akan berfungsi untuk kontributor baru.

Ingat, pengembang yang mengandalkan instruksi ini bisa jadi Anda setelah tidak mengerjakan proyek selama beberapa waktu.

Berikan perintah untuk menjalankan kasus pengujian apa pun yang disediakan dengan kode sumber setelah build berhasil. Pengembang bersandar pada kasus pengujian ini untuk memastikan bahwa mereka tidak merusak kode Anda saat mereka membuat perubahan. Kasus pengujian yang baik juga berfungsi sebagai sampel yang dapat digunakan pengembang untuk membangun kasus pengujian mereka sendiri saat menambahkan fungsionalitas baru.

Membantu pengguna berkontribusi

Bagian terakhir dari readme Anda membantu pengguna dan pengembang untuk terlibat dalam melaporkan masalah dan menyarankan ide untuk membuat kode Anda lebih baik. Pengguna harus ditautkan ke saluran tempat mereka dapat membuka bug, meminta fitur, atau mendapatkan bantuan menggunakan kode Anda.

Pengembang perlu mengetahui aturan apa yang perlu mereka ikuti untuk menyumbang perubahan, seperti panduan pengodean/pengujian dan persyaratan permintaan pull. Jika Anda memerlukan perjanjian kontributor untuk menerima permintaan pull atau menerapkan kode etik komunitas, proses ini harus ditautkan ke atau didokumentasikan di bagian ini. Tentukan lisensi apa yang dirilis kode di bawah dan tautkan ke teks lengkap lisensi.