Ajoutons `ARCHITECTURE.md`

 (matklad.github.io)
26 points par xguru 2021-02-08 | 1 commentaires | Partager sur WhatsApp

  • Un texte qui propose d’ajouter au dépôt un fichier expliquant l’architecture du projet afin de faciliter la participation à l’open source

  • La plus grande différence entre les contributeurs occasionnels et les développeurs principaux d’un projet est leur niveau de compréhension de l’architecture du projet

  • Quand on n’est pas familier de la structure, il faut plus de deux fois plus de temps pour écrire un patch, mais plus de dix fois plus de temps pour identifier l’endroit à modifier

  • Rédiger un fichier comme ARCHITECTURE.md qui décrit l’architecture à haut niveau

→ Le garder court pour que tout le monde puisse le lire, et ne documenter que les parties qui changent peu

→ Ne pas chercher à le synchroniser avec le code, mais le relire environ deux fois par an

Comment rédiger le contenu

  • Commencer par une vue d’ensemble du problème que l’on cherche à résoudre (bird’s-eye view)

  • Ajouter une cartographie du code un peu plus détaillée : « Où se trouve ce qui fait X ? »

  • Expliquer les grands modules et leurs relations : renvoyer vers d’autres documents pour ce que fait chaque module

  • Indiquer les noms des fichiers, modules et types importants

→ Pour que le lecteur puisse les rechercher par nom, et ne pas mettre de lien direct (car ils pourraient se casser)

  • Indiquer clairement les couches et les frontières entre les systèmes
  • Bons exemples

À lire aussi

1 commentaires

 
xguru 2021-02-08

Et l’idée d’ajouter, si possible, dans le README.md principal une explication de chaque dossier du projet est bonne aussi.

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

Si possible, ce serait bien d’ajouter une description pour chaque dossier, et ce serait encore mieux si GitHub pouvait afficher au niveau supérieur le contenu d’un README présent dans un dossier.

À ce sujet, consultez aussi les Architecture Decision Records.