Implementación de la automatización de la documentación del historial de Git
La publicación automatizada del historial de "commits" de Git, las notas de publicación y la documentación de la API agiliza el proceso de creación de documentación de publicación completa y actualizada para proyectos de software. Esto ayuda a los desarrolladores a hacer un seguimiento y comunicar los cambios introducidos en cada versión,promoviendo la transparencia y la colaboración.
La automatización de la generación de la documentación de las API garantiza su sincronización con los cambios en el código, proporcionando a los desarrolladores información precisa sobre el acceso a las API y su funcionalidad. La incorporación de resúmenes del historial de Git en la documentación de las versiones ofrece un contexto y una trazabilidad adicionales, lo que facilita los ciclos de publicación sin fricciones y mejora la administración general del proyecto. Juntos, estos esfuerzos de automatización optimizan los flujos de trabajo de documentación, ahorrando tiempo y esfuerzo al tiempo que mejoran la calidad y coherencia de la documentación de lanzamiento.
El proceso de implementación de esta funcionalidad puede dividirse en las siguientes actividades.
Automatización de la generación de documentación de API
Utilice OpenAPI (antes Swagger) u otras herramientas de documentación de API para generar automáticamente documentación de API a partir de su código base. Integre este proceso en su proceso de canalización de CI/CD para asegurarse de que la documentación de la API está actualizada y refleja los últimos cambios en sus puntos de conexión de la API. Como alternativa, considere herramientas como Swagger Codegen o Redocly para automatizar la generación de documentación de API a partir de su archivo de especificación OpenAPI o anotaciones de código.
Generación de notas de publicación a partir del historial de Git
Utilice comandos de Git o herramientas como GitChangelog para automatizar la generación de notas de publicación a partir del historial de confirmaciones de Git. Se trata de analizar los mensajes de confirmación y extraer la información pertinente, como las funciones agregadas y los errores corregidos. Personalice el formato de las notas de publicación para incluir detalles como el autor de la confirmación, la fecha y hora, el mensaje de confirmación y las solicitudes de extracción o incidencias asociadas.
Inclusión del historial de Git en la documentación de la versión
Incorpore resúmenes del historial de Git o registros de cambios en la documentación de la versión, junto con las notas de la versión y la documentación de la API. Esto proporciona un contexto y una transparencia adicionales en relación con los cambios introducidos en cada versión. Utilice Markdown u otros formatos de documentación para estructurar y presentar el historial de Git de forma clara y fácil de comprender.
Integración de notas de publicación en la canalización de documentación
Integre la generación de notas de publicación en la canalización de documentación o flujo de trabajo CI/CD. Esto garantiza que las notas de la versión se actualicen automáticamente y se incluyan en la documentación de la versión siempre que se etiquete una nueva versión o se genere una versión. Utilice secuencias de comandos o herramientas de automatización como Azure Pipelines o Acciones de GitHub para activar la generación de notas de publicación como parte del proceso de creación de documentación.
Automatización de la publicación de documentación
Automatice la publicación de su documentación de lanzamiento, incluidas las notas de lanzamiento, la documentación de la API y los resúmenes del historial de Git, en una ubicación central accesible para todos los equipos y partes interesadas de su organización. Aproveche las páginas de GitHub, los wikis de Azure DevOps o los servicios de alojamiento de documentación dedicados para publicar su documentación.