Implémenter l’automatisation de la documentation de l’historique Git
La publication automatisée de l’historique des validations Git, des notes de publication et de la documentation de l’API simplifie le processus de création d’une documentation complète et up-to-date de publication pour les projets logiciels. Cela permet aux développeurs de suivre et de communiquer les modifications introduites dans chaque version, en favorisant la transparence et la collaboration.
L’automatisation de la génération de la documentation des API garantit sa synchronisation avec les modifications de code, fournissant aux développeurs des informations précises sur l’accès aux API et leurs fonctionnalités. L’incorporation de résumés d’historique Git dans la documentation de mise en production offre un contexte et une traçabilité supplémentaires, ce qui facilite les cycles de publication sans friction et améliore la gestion globale des projets. Ensemble, ces efforts d’automatisation optimisent les flux de travail de documentation, économisent du temps et des efforts tout en améliorant la qualité et la cohérence de la documentation de mise en production.
Le processus d’implémentation de cette fonctionnalité peut être divisé en activités suivantes.
Automatisation de la génération de la documentation de l’API
Utilisez OpenAPI (anciennement Swagger) ou d’autres outils de documentation d’API pour générer automatiquement la documentation de l’API à partir de votre codebase. Intégrez ce processus à votre pipeline CI/CD pour vous assurer que la documentation de l’API est mise à jour et reflète les dernières modifications apportées à vos points de terminaison d’API. Vous pouvez également envisager des outils tels que Swagger Codegen ou Redocly pour automatiser la génération de la documentation de l’API à partir de votre fichier de spécification OpenAPI ou des annotations de code.
Génération de notes de publication à partir de l’historique Git
Utilisez des commandes git ou des outils tels que GitChangelog pour automatiser la génération de notes de publication à partir de l’historique de validation Git. Cela implique l’analyse des messages de validation et l’extraction d’informations pertinentes telles que les ajouts de fonctionnalités et les correctifs de bogues. Personnalisez le format des notes de publication pour inclure des détails tels que l’auteur de validation, l’horodatage, le message de validation et les demandes ou problèmes de tirage associés.
Inclusion de l’historique Git dans la documentation de mise en production
Incorporez des résumés d’historique Git ou des journaux de modification dans votre documentation de mise en production en même temps que les notes de publication et la documentation de l’API. Cela fournit un contexte et une transparence supplémentaires concernant les modifications introduites dans chaque version. Utilisez Markdown ou d’autres formats de documentation pour structurer et présenter l’historique Git de manière claire et facile à comprendre.
Intégration de notes de publication dans le pipeline de documentation
Intégrez la génération de notes de publication dans votre pipeline de documentation ou flux de travail CI/CD. Cela garantit que les notes de publication sont automatiquement mises à jour et incluses dans votre documentation de publication chaque fois qu’une nouvelle version est marquée ou qu’une version est générée. Utilisez des outils de script ou d’automatisation comme Azure Pipelines ou GitHub Actions pour déclencher la génération de notes de publication dans le cadre du processus de génération de documentation.
Automatisation de la publication de la documentation
Automatisez la publication de votre documentation de publication, notamment les notes de publication, la documentation des API et les résumés de l’historique Git, dans un emplacement central accessible à toutes les équipes et parties prenantes de votre organisation. Tirez parti des pages GitHub, des wikis Azure DevOps ou des services d’hébergement de documentation dédiés pour publier votre documentation.