Organisasi Alur Kerja Dokumen

Tim Dokumentasi Fedora Last review: 2023-04-24
Panduan ini menyajikan kepada anggota Docs dan calon kontributor daftar label dan kategori yang terkait dengan Issues dan Merge Requests di repositori GitLab Docs.

Tim Fedora Docs telah menyepakati organisasi alur kerja, yang berpusat pada dua halaman utama:

Dashboard GitLab

Merge Request GitLab yang Dibuka

Papan masalah dan label

Ada empat label yang digunakan untuk mengklasifikasikan status tiket masalah.

  • Triage: Masalah telah diberi label, tetapi belum ada yang ditugaskan. Apakah Anda ingin mengambil alih? Silakan menugaskan diri Anda sendiri dan pindahkan masalah ke status "Dalam proses".

  • In progress: Seseorang telah ditugaskan untuk menangani masalah ini dan saat ini sedang dalam proses.

  • Support needed: Sesuatu sudah dilakukan, tetapi seseorang harus mendukung penugasan yang sudah ada atau mengambil alih penugasan tersebut sepenuhnya.

  • Approval needed: Ini adalah perubahan besar dan memerlukan persetujuan dari pihak lain selain penugas. Silakan mengambil alih persetujuan sehingga penugas dapat melakukan penggabungan setelahnya.

"Permohonan Gabungan yang Terbuka" tidak memiliki dasbor. Anda dapat melihat semua label yang ditugaskan pada Permohonan Gabungan yang Terbuka dengan sekilas saat membuka halaman "Permohonan Gabungan yang Terbuka".

Selain itu, terdapat tiga label yang mengklasifikasikan jenis tiket masalah.

  • Major change: Ini adalah perubahan besar pada halaman Docs. Perubahan ini memerlukan Merge Request (Merge Request) dan harus disetujui oleh orang lain selain penugas sebelum dapat digabungkan.

  • Minor change: Ini hanyalah perubahan kecil pada halaman Docs. Perubahan ini tidak memerlukan persetujuan, dan dapat langsung diterapkan (Merge Request tidak wajib).

  • Tugas internal: Ini adalah tugas internal Fedora Docs yang bukan merupakan perubahan, perbaikan, atau pembaruan pada halaman/konten Docs. (Contoh: mempersiapkan pertemuan atau mengevaluasi survei).

Setiap tiket masalah dan setiap Merge Request yang terbuka harus diberi label tambahan dengan salah satu dari tiga label ini. Label jenis tidak berubah selama alur kerja.

Selain label negara dan label jenis, tiket masalah dan Merge Request dapat diberi label tambahan sebagai "good first issue". Ingin berkontribusi pada Fedora Docs? Ini adalah kesempatan Anda. Silakan berkomentar pada salah satu tiket masalah ini yang ingin Anda ambil alih sendiri.

Selain itu, terdapat label tambahan untuk Merge Requests yang berpotensi memengaruhi lebih dari satu cabang, yang berarti mereka memerlukan Merge Requests lanjutan atau cherry-picks. Label multiple MR likely memastikan bahwa semua cabang yang terpengaruh diidentifikasi dan diperbarui, serta Merge Requests tidak digabungkan tanpa tinjauan MR.

Bagaimana cara membuat tiket masalah dan Merge Request

Ada dua cara untuk membuat tiket dan Merge Request: secara eksternal dan internal.

  • Jika dibuat secara eksternal, mereka dibuat oleh orang-orang di luar tim Fedora Docs, yang membukanya di GitLab atau menggunakan tombol "Laporkan Masalah" (membuat tiket masalah) / "Edit Halaman Ini" (membuat Merge Request) di halaman Fedora Docs mana pun (tombol-tombol tersebut berada di pojok kanan atas). Tiket akan muncul dalam daftar "Open" di dashboard tanpa label apa pun. Permintaan Merge akan muncul di halaman Permintaan Merge Terbuka tanpa label apa pun.

  • Jika dibuat secara internal, salah satu anggota Tim Dokumen membukanya. Dalam kondisi terbaik, anggota ini sudah menetapkan label jenis dan memasukkan tiket masalah ke dalam daftar "Triage", di mana tiket tersebut dapat menunggu penugas untuk mengambil alih. Hal yang sama berlaku untuk Merge Request, meskipun mereka tidak memiliki daftar seret dan lepas, dan label "Triage" harus ditetapkan secara manual seperti halnya label jenis. Sebagai alternatif, anggota yang membuatnya dapat langsung menugaskan penanggung jawab ke tiket masalah / Merge Request, lalu menyeret (drag & drop) tiket masalah ke daftar "In progress" (ini berarti menambahkan label "In progress") di dashboard, atau menambahkan label "In progress" secara manual jika itu adalah Merge Request.

Di dashboard, tiket masalah dapat dipindahkan ke daftar lain dengan drag and drop. Label status akan berubah sesuai dengan pergerakan tiket. Jika tiket dipindahkan dari "Triage" ke "In progress" dengan drag and drop, label status akan berubah dari ‘Triage’ menjadi "In progress". Oleh karena itu, label jenis yang persisten hanya perlu diatur secara manual sekali saat tiket baru dibuat. Hal ini tidak berlaku untuk Merge Requests di halaman Open Merge Request. Saat membuat tiket masalah di dashboard, Anda akan diminta untuk memilih di mana tiket masalah akan dibuat. Jika Anda tidak yakin di mana harus membuat tiket masalah, buatlah di Fedora / Fedora Docs / Docs Website / Fedora Docs pages. Anda akan melihat ini di daftar "Proyek" ("Pilih proyek") yang ditampilkan saat Anda mengklik untuk membuat tiket masalah. Nantinya, ini akan ditampilkan sebagai "fedora/docs/docs-website/pages".

Alur kerja

Perubahan kecil

Jika dilakukan oleh anggota Docs dan jika perubahan tersebut jelas merupakan "Perubahan minor", perubahan dapat dilakukan melalui commit langsung tanpa perlu mengajukan Merge Request atau tiket masalah. Jika pihak eksternal mengajukan Merge Request sebagai "Perubahan minor", anggota Docs akan menggabungkannya segera setelah mereka menugaskan diri sendiri dan meninjau Merge Request tersebut. Namun, selalu periksa apakah perubahan tersebut berlaku untuk beberapa cabang.

Jika beberapa cabang terpengaruh oleh "Perubahan Kecil", Anda hanya diperbolehkan untuk melakukan merge/commit secara langsung jika Anda melakukan merge/commit dan cherry-pick ke semua cabang yang terpengaruh secara bersamaan. Jika Anda ragu, tambahkan label "multiple MR likely" secara tambahan ke label "Minor change" dan biarkan Permintaan Merge tetap terbuka untuk diskusi.

Depending on the following discussion, the "multiple MR likely" label will be removed if there are no other affected branches and then the merge or commit can be made, or if other branches are affected, the merge or commit can be conducted and a cherry-pick to all affected branches will be done immediately and at once with the merge or commit. The goal to achieve here is that a Merge Request does not disappear from the Open Merge Request page until the update of all affected branches is complete.

Jika diskusi berlangsung dalam tiket masalah (menggunakan commit alih-alih Merge Request, atau menggunakan beberapa Merge Request yang digabungkan dalam satu tiket) dan bukan dalam satu Merge Request, commit dan cherry-pick dapat dilakukan secara terpisah.

Alur kerja untuk Perubahan kecil adalah sebagai berikut:

  1. Jika ini hanya commit yang jelas merupakan "Perubahan kecil", lakukan saja. Jika Anda tahu cabang mana yang terpengaruh dan jika Anda dapat melakukan commit dan semua cherry-pick terkait, silakan lanjutkan. Jika Anda tidak memiliki cukup waktu untuk menyelesaikan tugas ini, lakukan sebagai berikut:

  2. Tentukan jenisnya dan berikan label jenis yang terkait ("Perubahan kecil", "Perubahan besar", "Tugas internal". Di sini: Perubahan kecil) pada Merge Request yang sudah ada atau tiket masalah yang sudah ada, atau jika belum ada yang ada: buatlah satu! Jika Anda tidak yakin apa yang harus dibuat, buatlah tiket masalah.

  3. Pindahkan masalah baru ke daftar "Triage" (yang, seperti dijelaskan di atas, secara otomatis memberikan label status ‘Triage’), atau tambahkan label "Triage" secara manual jika itu adalah Merge Request.

  4. Tiket masalah atau Merge Request dapat ditugaskan kepada anggota yang akan mengambil alih. Setelah seseorang ditugaskan, tiket harus dipindahkan ke status "Dalam proses" (perubahan ke status "Dalam proses" harus dilakukan secara manual untuk Merge Request).

  5. Ada beberapa pilihan.

    1. Penerima tugas menyelesaikan tiket masalah/MR, dan sesuai dengan itu, memindahkan/menempatkan tiket tersebut dari label status saat ini ke "Tutup". Jika beberapa cabang perlu diubah dan jika kasus ditangani dalam sebuah MR, semua cabang harus diubah secara bersamaan.

    2. Alternatifnya, penerima tugas memerlukan dukungan atau pendapat tambahan: tiket/MR dipindahkan ke "Dibutuhkan Dukungan" untuk mengidentifikasi pendukung (yang dapat, tetapi tidak wajib, ditugaskan sebagai penerima tugas tambahan jika itu masuk akal) dan setelah cukup banyak pendukung diidentifikasi, pindahkan/kembalikan ke "Dalam Proses". Gunakan "Dibutuhkan Dukungan" untuk mendorong diskusi dalam tiket/MR dan mendapatkan pendapat tambahan. Setelah semua pekerjaan selesai, tiket/MR dapat dipindahkan/diletakkan ke "Tutup". Jika beberapa cabang perlu diubah dan kasus ditangani dalam MR, semua cabang harus diubah sekaligus. Anggota bebas untuk mengalihkan masalah (Contoh: jika orang lain memiliki pengalaman lebih dalam tugas tersebut, atau dapat menginvestasikan lebih banyak waktu).

    3. Jika penugas tidak dapat lagi menangani masalah tersebut, penugas dapat mengubah label masalah menjadi "Membutuhkan dukungan" dan mencari penugas baru, atau membuat komentar tentang pekerjaan yang telah selesai dan pekerjaan yang masih tersisa, menghapus penugas, dan mengubah status menjadi "Triage".

Perubahan besar

"Multiple MR kemungkinan besar" dapat dipindahkan ke "Perubahan besar", yang memerlukan tiket masalah atau Merge Request.

Alur kerja untuk perubahan besar adalah sebagai berikut:

  1. Tentukan jenis dan ubah label Merge Request atau tiket masalah menjadi Perubahan Besar.

  2. Pindahkan masalah baru ke daftar "Triage", atau tambahkan label "Triage" secara manual jika itu adalah Merge Request.

  3. Tiket masalah atau Merge Request dapat dialihkan ke anggota lain. Setelah seseorang ditugaskan, tiket akan berpindah ke status "Dalam proses" (perubahan ke "Dalam proses" dilakukan secara manual untuk Merge Request).

  4. Ada beberapa pilihan.

    1. Penerima tugas menyelesaikan pekerjaan aktif* pada tiket masalah/MR, dan memindahkan/menempatkan tiket tersebut dari label status saat ini ke "Approval needed".

    2. Alternatifnya, penugas memerlukan dukungan atau pendapat tambahan. Tiket/MR dipindahkan ke "Dibutuhkan Dukungan" untuk mengidentifikasi pendukung. Setelah cukup banyak pendukung bersedia, pindahkan masalah kembali ke "Dalam Proses". "Dibutuhkan dukungan" juga dapat digunakan untuk mendorong diskusi dalam tiket/MR guna mendapatkan pendapat tambahan. Setelah selesai, tiket/MR dapat dipindahkan ke "Dibutuhkan persetujuan". Ubah penanggung jawab menjadi seseorang yang memiliki pengalaman lebih dalam tugas berikutnya, atau dapat menginvestasikan lebih banyak waktu.

Jika beberapa cabang terpengaruh, tambahkan label "multiple MR likely". Jika label ini diberikan, pembahasan dalam tiket/MR harus mengidentifikasi semua cabang yang terpengaruh. Pada akhirnya, Merge Request harus ditransfer ke semua cabang yang terpengaruh melalui cherry-picks. Jika beberapa cabang harus diubah, semua perubahan harus dilakukan secara bersamaan.

Jangan gunakan cabang "stg" untuk konten. Bekerja di cabang atau garpu yang khusus untuk masalah spesifik yang sedang Anda kerjakan.

Tugas internal

Tugas internal bersifat fleksibel. Tugas dimulai dari status "Open" atau "Triage", dan bergerak melalui tahap ‘Triage’, "In progress", "Support needed" hingga "Closed".

Peran rapat mingguan

Pertemuan mingguan Docs membantu mengidentifikasi dan menangani masalah dan tugas yang tidak biasa atau tidak terjadi secara teratur. Di sisi lain, organisasi alur kerja dirancang untuk mengelola operasi sehari-hari yang terstandarisasi dari Fedora Docs.

Tiket masalah dan Merge Request dari organisasi alur kerja dapat menjadi topik rutin dalam rapat mingguan.

  • Periksa apakah ada perkembangan tak terduga dalam alur kerja yang memerlukan pembahasan.

  • Identifikasi dan tetapkan tiket masalah dan MR yang belum ditugaskan selama lebih dari dua minggu, serta diskusikan tiket yang masih terbuka satu bulan setelah ditugaskan.

  • Gunakan label Meeting untuk masalah atau MR yang akan dibahas dalam pertemuan Docs.

Want to help? Learn how to contribute to Fedora Docs ›