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. File README Anda harus ditujukan untuk audiens berikut:
- Pengguna yang 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 file README Anda di Markdown alih-alih teks biasa. Markdown memudahkan untuk memformat teks, menyertakan gambar, dan menautkan ke lebih banyak dokumentasi dari file README Anda.
Berikut adalah beberapa file README yang menggunakan format ini dan berbicara dengan ketiga audiens. Gunakan untuk referensi dan inspirasi:
Prasyarat
| Kategori | Persyaratan |
|---|---|
| Akses proyek | Anggota proyek . |
| Permissions | - Lihat kode dalam proyek privat: Minimal akses Dasar . - Mengkloning atau berkontribusi pada kode dalam proyek privat: Menjadi anggota dari grup keamanan Kontributor atau memiliki izin yang diperlukan dalam proyek. - Mengatur izin cabang atau repositori: Mengelola izin adalah izin untuk cabang atau repositori. - Mengubah cabang default: Kebijakan pengeditan merupakan 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. |
| Services | Repos diaktifkan. |
| Tools | Fakultatif. Gunakan az repos perintah: 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 . |
| Permissions | - Lihat kode: Setidaknya akses Dasar. - Mengkloning atau berkontribusi pada kode: Anggota kelompok keamanan Kontributor atau memiliki izin yang sesuai di dalam proyek. |
| Services | Repos diaktifkan. |
Membuat pengantar
Mulai file README Anda dengan penjelasan singkat yang menjelaskan proyek Anda. Tambahkan cuplikan layar atau ANIMASI GIF dalam pengenalan Anda jika proyek Anda memiliki antarmuka pengguna. Jika kode Anda bergantung pada aplikasi atau pustaka lain, pastikan untuk menyatakan dependensi tersebut dalam pengenalan atau tepat di bawahnya. Aplikasi dan alat yang hanya berjalan pada platform tertentu harus memiliki versi sistem operasi yang didukung yang dicatat di bagian file README ini.
Membantu pengguna Anda memulai
Di bagian berikutnya dari file README Anda, pandu pengguna melalui membuat kode Anda aktif dan berjalan pada sistem mereka sendiri. Tetap fokus pada langkah-langkah penting untuk memulai kode Anda. Berikan tautan ke versi yang diperlukan dari perangkat lunak prasyarat yang dibutuhkan sehingga pengguna dapat mengaksesnya dengan mudah. Jika Anda memiliki langkah penyiapan yang kompleks, dokumentasikan di luar file README Anda dan tautkan ke sana.
Beri tahu pembaca tempat untuk mendapatkan rilis terbaru. Berikan salah satu item berikut:
- Tautan ke alat penginstal biner atau paket bawaan.
- Instruksi penginstalan dengan menggunakan manajer paket (misalnya, penginstalan npm, penginstalan pip, atau paket penambahan dotnet).
Jika proyek Anda adalah pustaka atau pembungkus API, sertakan cuplikan kode minimal yang menunjukkan penggunaan dasar, diikuti oleh output yang diharapkan. Informasi ini membantu pembaca memverifikasi penyiapan mereka dan memahami apa yang dilakukan pustaka secara sekilas.
Menyediakan langkah-langkah build untuk pengembang
Gunakan bagian berikutnya dari file README Anda untuk menunjukkan kepada pengembang cara membangun kode Anda dari klon baru repositori dan menjalankan pengujian yang disertakan. Lakukan langkah-langkah 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.
- Jalankan melalui instruksi saat Anda menulisnya untuk memverifikasi bahwa instruksi berfungsi untuk kontributor baru.
Ingat, Anda mungkin pengembang yang bergantung pada instruksi ini setelah tidak mengerjakan proyek selama beberapa waktu.
Sertakan 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 ketika mereka menambahkan fungsionalitas baru.
Membantu pengguna berkontribusi
Bagian terakhir dari file 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 di bawah mana kode ini dirilis, dan tautkan ke teks lengkap lisensi.