Mari tambahkan ARCHITECTURE.md

• Tulisan yang mengusulkan agar menambahkan file ke repo yang menjelaskan arsitektur proyek untuk mempermudah partisipasi dalam open source

• Perbedaan terbesar antara orang yang sesekali berkontribusi ke proyek dan pengembang inti adalah tingkat pemahaman mereka terhadap arsitektur proyek

• Jika belum terbiasa dengan strukturnya, waktu untuk menulis patch bisa memakan lebih dari 2 kali lipat, tetapi untuk mengetahui lokasi yang harus diperbaiki bisa memakan waktu lebih dari 10 kali lipat

• Tulis file seperti ARCHITECTURE.md yang menjelaskan arsitektur tingkat tinggi

→ Tulis secara singkat agar siapa pun bisa membacanya, dan rangkum hanya bagian-bagian yang tidak sering berubah

→ Jangan mencoba menyinkronkannya dengan kode, cukup tinjau ulang sekitar 2 kali setahun

Cara menulis isinya

• Mulai dengan gambaran umum (bird's eye view) tentang masalah yang ingin diselesaikan

• Peta kode yang sedikit lebih rinci: "Di mana letak hal yang melakukan X?"

• Jelaskan modul-modul secara garis besar dan hubungan di antaranya: untuk tugas masing-masing modul, tautkan ke dokumen lain

• Cantumkan nama file, modul, dan tipe yang penting

→ Agar pembaca bisa mencarinya berdasarkan nama, dan jangan buat tautan langsung (karena tautan bisa rusak)

• Tegaskan batas antar layer dan sistem

• Contoh yang baik

• Rust Analyzer Architecture.md - https://github.com/rust-analyzer/rust-analyzer/…

• Caddy Architecture : https://caddyserver.com/docs/architecture

[xguru]

Dan menurut saya, usulan untuk menambahkan penjelasan tentang tiap folder proyek di README.md utama jika memungkinkan juga bagus.

• https://news.ycombinator.com/item?id=26050082

Contoh: https://github.com/diem/diem/…

Kalau memungkinkan, akan bagus juga jika ditambahkan penjelasan di tiap folder, dan GitHub menampilkan isi README folder tersebut dari level atas.

Terkait hal ini, silakan lihat juga Architecture Decision Records.

• Alasan harus menulis ADR https://id.news.hada.io/topic?id=2665