¿Debería almacenarse la documentación generada en un repositorio Git?

Cuando usa herramientas como jsdocs , genera archivos HTML estáticos y sus estilos en su base de código en función de los comentarios en su código.

¿Deben registrarse estos archivos en el repositorio de Git o deben ignorarse con .gitignore?

En ausencia de cualquier necesidad específica, cualquier archivo que pueda construirse, recrearse, construirse o generarse a partir de herramientas de compilación utilizando otros archivos registrados en el control de versiones no debe registrarse. Cuando el archivo es necesario, puede (re) construirse desde el otro fuentes (y normalmente sería como algún aspecto del proceso de construcción).

Por lo tanto, esos archivos deben ignorarse con .gitignore.

Mi regla es que cuando clono un repositorio y presiono el botón "construir", luego, después de un tiempo, todo está construido. Para lograr esto para su documentación generada, tiene dos opciones: o alguien es responsable de crear estos documentos y ponerlos en git, o documenta exactamente qué software necesito en mi máquina de desarrollo, y se asegura de presionar "construir" El botón construye toda la documentación en mi máquina.

En el caso de la documentación generada, donde cualquier cambio que realice en un archivo de encabezado debería cambiar la documentación, es mejor hacerlo en la máquina de cada desarrollador, porque quiero la documentación correcta todo el tiempo, no solo cuando alguien la ha actualizado. Hay otras situaciones en las que generar algo puede llevar mucho tiempo, ser complicado, requerir un software para el que solo tienes una licencia, etc. En ese caso, es mejor darle a una persona la responsabilidad de poner las cosas en juego.

@Curt Simpson: Tener todos los requisitos de software documentados es mucho mejor de lo que he visto en muchos lugares.

Estos archivos no deben registrarse porque los datos para generarlos ya están presentes. No desea almacenar datos dos veces (SECO).

Si tiene un sistema CI, quizás podría hacer que compile los documentos y los almacene para esa compilación / publíquelos en un servidor web.

Una ventaja de tenerlos en algún repositorio (ya sea el mismo o uno diferente, preferiblemente generado automáticamente) es que puede ver todos los cambios en la documentación. A veces, esas diferencias son más fáciles de leer que las diferencias del código fuente (específicamente si solo le importan los cambios de especificación, no la implementación).

Pero en la mayoría de los casos no es necesario tenerlos en el control de la fuente, como explicaron las otras respuestas.

Ignorado De todos modos, querrá que los usuarios del repositorio puedan reconstruirlos, y elimina la complejidad de asegurarse de que los documentos estén siempre sincronizados. No hay razón para no tener los artefactos construidos agrupados en un solo lugar si desea tener todo en un solo lugar y no tener que construir nada. Sin embargo, los repositorios de origen no son realmente un buen lugar para hacer esto, ya que la complejidad allí duele más que la mayoría de los lugares.

Depende de su proceso de implementación. Pero confirmar los archivos generados en un repositorio es una excepción y debe evitarse, si es posible. Si puede responder las dos preguntas siguientes con Sí , el registro de sus documentos podría ser una opción válida:

• ¿Son los documentos un requisito para la producción?
• ¿Su sistema de implementación carece de las herramientas necesarias para construir los documentos?

Si estas condiciones son verdaderas, probablemente esté implementando con un sistema heredado o un sistema con restricciones de seguridad especiales. Como alternativa, puede confirmar los archivos generados en una rama de lanzamiento y mantener limpia la rama maestra.

Depende. Si esos documentos:

• Debe ser parte del repositorio, como el readme.md, entonces se prefiere mantenerlos en el repositorio de git. Porque puede ser complicado manejar esas situaciones de forma automatizada.

• Si no tiene una forma automatizada de construirlos y actualizarlos, como un sistema de CI, y está destinado a ser visto por la audiencia general, se prefiere mantenerlos en el repositorio de git.

• Toma MUCHO tiempo construirlos, entonces es justificable conservarlos.

• Están destinados a ser vistos para la audiencia general (como el manual del usuario), y lleva un tiempo considerable construirlos, mientras que sus documentos anteriores se vuelven inaccesibles (fuera de línea), entonces es justificable mantenerlos en el repositorio de git.

• Están destinados a ser vistos para la audiencia general y tienen que mostrar un historial de sus cambios / evolución, podría ser más fácil mantener comprometidas las versiones anteriores del documento y construir / comprometer la nueva vinculada a la anterior. Justificable.

• Tiene una razón específica aceptada para que todo el equipo se comprometa, entonces es justificable mantenerlos en el repositorio de git. (No sabemos su contexto, usted y su equipo sí)

En cualquier otro escenario, debe ignorarse con seguridad.

Sin embargo, si es justificable mantenerlos en el repositorio de git, podría ser un signo de otro problema mayor que enfrenta su equipo. (No tener un sistema de CI o problemas de rendimiento horribles similares, enfrentarse al tiempo de inactividad mientras se construye, etc.)

Como principio del control de versiones, solo los "objetos primarios" deben almacenarse en un repositorio, no los "objetos derivados".

Hay excepciones a la regla: a saber, cuando hay consumidores del repositorio que requieren los objetos derivados y se espera razonablemente que no tengan las herramientas necesarias para generarlos. Otras consideraciones influyen, ¿es la cantidad de material difícil de manejar? (¿Sería mejor para el proyecto simplemente hacer que todos los usuarios tengan las herramientas?)

Un ejemplo extremo de esto es un proyecto que implementa un lenguaje de programación poco común cuyo compilador está escrito en ese lenguaje (ejemplos bien conocidos incluyen Ocaml o Haskell) Si solo el código fuente del compilador está en el repositorio, nadie puede construirlo; no tienen una versión compilada del compilador que puedan ejecutar en la máquina virtual, de modo que puedan compilar el código fuente de ese compilador. Además, las características más recientes del lenguaje se usan inmediatamente en la fuente del compilador en sí, por lo que siempre se requiere cerca de la última versión del compilador para compilarlo: un ejecutable del compilador de un mes de antigüedad obtenido por separado no compilará el código actual porque el código usa funciones de lenguaje que no existían hace un mes. En esta situación, es casi seguro que la versión compilada del compilador debe registrarse en el repositorio y mantenerse actualizada.