Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Layanan Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022
Repositori Git Anda harus memiliki file readme sehingga penonton tahu apa yang dilakukan kode Anda dan bagaimana mereka dapat mulai menggunakannya. Readme Anda harus ditujukan kepada pembaca 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 berkaitan dengan ketiga jenis pembaca, dapat dijadikan referensi dan inspirasi.
Prasyarat
| Kategori | Persyaratan |
|---|---|
| Akses proyek | Anggota proyek . |
| Izin | - Lihat kode dalam proyek privat: Minimal akses Dasar . - Mengkloning atau berkontribusi pada kode dalam proyek privat: Anggota grup keamanan Kontributor atau izin-izin yang sesuai di dalam proyek. - Mengatur izin cabang atau repositori: Mengelola izin untuk cabang atau repositori. - Ubah cabang default: Edit kebijakan izin untuk repositori. - Impor repositori: Anggota Administrator Proyek grup keamanan atau tingkat proyek Git Membuat repositori izin diatur ke Izinkan. Untuk informasi selengkapnya, lihat Mengatur izin repositori Git. |
| Layanan | Repos diaktifkan. |
| Alat | Fakultatif. Gunakan perintah az repos: Azure DevOps CLI. |
Nota
Dalam proyek publik, pengguna dengan akses Stakeholder memiliki akses penuh ke Azure Repos, termasuk melihat, menyalin, dan berkontribusi pada kode.
| Kategori | Persyaratan |
|---|---|
| Akses proyek | Anggota proyek . |
| Izin | - Lihat kode: Setidaknya akses Dasar. - Mengkloning atau berkontribusi pada kode: Anggota kelompok keamanan Kontributor atau memiliki izin yang sesuai di dalam proyek. |
| Layanan | Repos diaktifkan. |
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 untuk menyiapkan dan menjalankan kode Anda di sistem mereka sendiri pada bagian selanjutnya dari readme Anda. Tetap fokus pada langkah-langkah penting untuk memulai kode Anda. Tautkan ke versi yang diperlukan dari perangkat lunak prasyarat mana pun sehingga pengguna dapat mengaksesnya dengan mudah. Jika Anda memiliki langkah-langkah penyiapan yang kompleks, dokumentasikan di luar readme Anda dan buat tautan ke langkah-langkah tersebut.
Jelaskan di mana untuk mendapatkan rilis terbaru kode Anda. Instalasi biner atau instruksi tentang menggunakan kode Anda dengan alat pengemasan merupakan pilihan 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 hal berikut:
- Berikan detail tentang alat yang diperlukan untuk membangun kode dan dokumentasikan langkah-langkah untuk mengonfigurasinya untuk mendapatkan build yang bersih.
- Pisahkan instruksi build yang padat atau kompleks ke halaman terpisah dalam dokumentasi kamu dan tautkan jika diperlukan.
- Tinjau instruksi yang Anda tulis untuk memastikan instruksi tersebut dapat digunakan oleh 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 kode dirilis dan tautkan ke teks lengkap lisensi tersebut.