Implemente a automação da documentação do histórico do Git
A publicação automatizada do histórico de commit do Git, das notas sobre a versão e da documentação da API simplifica o processo de criação da documentação de versão abrangente e atualizada para os projetos de software. Isso ajuda os desenvolvedores a controlar e comunicar as alterações introduzidas em cada versão, promovendo transparência e colaboração.
Automatizar a geração de documentação da API garante sua sincronização com as alterações de código, fornecendo aos desenvolvedores informações precisas sobre o acesso às APIs e suas funcionalidades. A incorporação de resumos do histórico do Git na documentação de versão oferece contexto e rastreabilidade adicionais, facilitando os ciclos de lançamento sem atrito e melhorando o gerenciamento geral do projeto. Juntos, esses esforços de automação otimizam os fluxos de trabalho da documentação, economizando tempo e esforço, ao mesmo tempo em que aprimoram a qualidade e a consistência da documentação de versão.
O processo de implementação dessa funcionalidade pode ser dividido nas atividades a seguir.
Automatizar a geração de documentação da API
Use o OpenAPI (antigo Swagger) ou outras ferramentas de documentação da API para gerar automaticamente a documentação da API da sua base de código. Integre esse processo ao pipeline de CI/CD para garantir que a documentação da API seja atualizada e reflita as alterações mais recentes nos pontos de extremidade da API. Como alternativa, considere ferramentas como o Swagger Codegen ou Redocly para automatizar a geração da documentação da API de seu arquivo de especificação OpenAPI ou anotações de código.
Gerar notas sobre a versão do histórico do Git
Use comandos ou ferramentas do Git, como o GitChangelog, para automatizar a geração de notas sobre a versão do histórico de commit do Git. Isso envolve analisar as mensagens do commit e extrair informações relevantes, como adições de recursos e correções de bug. Personalize o formato das notas sobre a versão para incluir detalhes como autor do commit, carimbo de data/hora, mensagem do commit e problemas ou pull requests associados.
Incluir o histórico do Git na documentação da versão
Incorpore resumos de histórico do Git ou logs de mudança na documentação de versão juntamente com as notas sobre a versão e a documentação da API. Isso fornece contexto e transparência adicionais em relação às alterações introduzidas em cada versão. Use o Markdown ou outros formatos de documentação para estruturar e apresentar o histórico do Git de maneira clara e fácil de compreender.
Integrar notas sobre a versão ao pipeline de documentação
Integre a geração de notas sobre a versão ao pipeline de documentação ou ao fluxo de trabalho de CI/CD. Isso garante que as notas sobre a versão sejam atualizadas automaticamente e incluídas na documentação da versão sempre que uma nova versão for marcada ou uma versão for gerada. Use ferramentas de script ou automação, como o Azure Pipelines ou o GitHub Actions, para disparar a geração de notas sobre a versão como parte do processo de compilação da documentação.
Automatizar a publicação da documentação
Automatize a publicação da documentação de versão, incluindo as notas sobre a versão, a documentação da API e os resumos do histórico do Git, para um localização central acessível a todas as equipes e stakeholders da sua organização. Aproveite o GitHub Pages, os wikis do Azure DevOps ou os serviços de hospedagem de documentação dedicada para publicar sua documentação.