¿Debería usarse Git para la documentación y la gestión de proyectos? ¿Debería el código estar en un repositorio separado?

68

Estoy iniciando un repositorio Git para un proyecto grupal. ¿Tiene sentido almacenar documentos en el mismo repositorio de Git que el código ? Parece que esto entra en conflicto con la naturaleza del flujo de revisión de Git .

Aquí hay un resumen de mis preguntas:

¿El estilo de revisión de Git será confuso si tanto el código como los documentos se registran en el mismo repositorio ? Experiencias con esto?
¿Es Git un buen ajuste para el control de revisión de documentación?
NO estoy preguntando si un Sistema de Control de Revisión en general debería o no debería usarse para la documentación, debería hacerlo.

Gracias por los comentarios hasta ahora!

git version-control project-management

— EmpireJones
fuente

Ah, está bien ... gracias por la aclaración. No veo por qué sería un problema, pero no tengo ninguna experiencia personal con GIT (solo una comprensión teórica), por lo que dejaré que alguien con experiencia más directa responda esa pregunta.

— Flimzy

1

No entiendo cómo es esto en el tema. Estás hablando de documentación de software y comprometiéndote con un DVCS

— Tim Post

Probablemente depende de la documentación y sus necesidades. ¿Necesita diffs y está en un formato que pueda manejarlo? Si git brinda los servicios requeridos seguro. Es mejor tener un sistema de gestión de documentos separado ...

— Rig

Si su documentación está en texto plano, bien. Si es un formato binario, esencialmente necesita un sistema de control de versiones que comprenda el formato binario; este es el bloqueo del proveedor en su forma más pura.

relacionado: ¿Qué parte de su proyecto debe estar en el control del código fuente?

— mosquito

53

Almacenamos documentación en SVN todo el tiempo. De hecho, todo nuestro manual de usuario está escrito en LaTeX y almacenado en SVN. Elegimos LaTeX específicamente porque es un lenguaje basado en texto y fácil de mostrar diferencias línea por línea.

También almacenamos algunos archivos sin formato de texto, como archivos .doc de Microsoft Office, hojas de cálculo, archivos .zip, etc., cuando es necesario ... pero parte del beneficio de un RCS se pierde cuando no puede ver el incremento diffs.

La clave es realmente asegurarse de que su documentación esté bien organizada, para que las personas puedan encontrar (y actualizar) la documentación (y la fuente) cuando la necesiten.

— Flimzy
fuente

11

Si es una tienda de Microsoft, TortoiseSVN admite las diferencias línea por línea de MS Office.

— Phil

2

Dejar caer formatos de documentos binarios haría del mundo un lugar mejor. o dado que los documentos son de texto plano, tampoco debería haber un problema real con un DVCS.

— Kai Inkinen

Ah, y la primera vez que escuché sobre TortoiseSVN y los archivos doc, entonces +1 para eso. Me pregunto si eso terminará en Tortoise [AnyDVCS] en cualquier momento en el futuro.

— Kai Inkinen

@ Phil: ¿Cómo lo logra TortoiseSVN? ¿El visor doc-diff está integrado con el cliente SVN o se puede usar de forma independiente?

— Flimzy

1

Una buena opción sería usar Pandoc para que la mayor parte de su documentación esté en Markdown, pero los bits cruciales aún pueden usar TeX. Como compila el Markdown para LaTeX, los resultados son los mismos. Sin embargo, esto también le permitiría exportarlo a diferentes formatos y facilitaría la lectura de la fuente.

— Tikhon Jelvis

22

Bueno, depende de qué formato utilice para la documentación. Si es algo basado en texto, todo está bien.

Git también puede almacenar contenido binario y puede realizar un seguimiento de las revisiones, pero la salida de diferencias no tendrá sentido.

También es posible almacenar documentación en el código en sí mismo, como perldoc pod, java también tiene algún formato / anotación para esto.

— cstamas
fuente

Estoy de acuerdo, aunque es posible almacenar documentación que no sea de texto, git funcionará mucho mejor si almacena texto en su lugar. Se ha hablado de un conductor diff que sabe cómo diff palabra (o similares) los documentos, pero no estoy seguro de si se implementa o no

— Sverre Rabbelier

Pensé que Word movió su formato de binario a XML.

— cledoux

3

@ karategeek6 El formato 'XML' de Word no es legible por humanos. Y una línea de texto no corresponde a una línea del XML de Word, incluso en aproximación. Por lo tanto, bien podría ser binario.

Puede indicar a Word que guarde su salida en XML sin comprimir. Elija Save As, luego seleccione en Word XML Document (*.xml)lugar del predeterminado Word Document (*.docx). El XML es bastante complejo, por lo que no garantiza que los cambios sean fáciles de leer, pero al menos no serán binarios.

— Kyralessa

> pero la salida diff no tendrá sentido. En caso de diferencias, podríamos abrir 2 revisiones de un documento una al lado de la otra y comparar con nuestros ojos :)

— Lucas

14

No puedo imaginar por qué crees que podría haber un problema al usar git, o cualquier otro sistema de control de versiones, para la documentación. Al igual que el código fuente, la documentación debe tener un historial completo y la capacidad de volver a una versión anterior si es necesario. Un sistema de control de versiones es perfecto para esto.

66

Solo si la documentación está en forma de texto. Los blobs binarios no se benefician completamente del control de versiones.

2

@ ThorbjørnRavnAndersen: Aun así, a menos que tenga un sistema de versiones específico de binario, probablemente sea mejor mantener incluso los archivos binarios en Git en lugar de hacerlo solo.

— Tikhon Jelvis

@TikhonJelvis No cuestioné si es una buena idea poner archivos binarios en git; si son los artefactos originales, lo es. Intente, sin embargo, ejecutar "git diff" en documentos de Word.

@ user1249: podría "exportar" la revisión 2 al escritorio, diga my_docs_rev15.docx y my_docs_rev14.docx, luego ábrala una al lado de la otra y compárela con sus ojos y cerebro, no es tan difícil :)

— Luke

14

Está claro que usar algún tipo de sistema de control de versiones para almacenar documentos es un nobrainer. La parte más interesante de la pregunta es si es una buena idea almacenar documentos en la MISMA ubicación como código fuente. El posible problema aquí es que podría ser difícil establecer diferentes privilegios de acceso para el código y la documentación en ese caso. Y en muchos casos comerciales, las personas necesitarán acceso a documentos pero no al código fuente, como los departamentos de marketing o BA.

— Ma99uS
fuente

3

Sí, el aspecto de "misma ubicación" es una de las partes clave de esta pregunta.

La misma ubicación es buena si puede administrarla, ya que evita la necesidad de tener conocimientos tribales (saber dónde buscar) o la necesidad de buscar dónde están las cosas.

— rapid_now

Es posible que no necesiten acceso al código, pero no debería doler que tengan ese acceso. No tienen que mirarlo. Los secretos generalmente no deberían estar en el control de versiones de todos modos.

— bdsl

9

En la empresa en la que trabajo ponemos documentación en SVN. Sin embargo, después de algunos conflictos y la necesidad de compartirlo, decidimos moverlo a Mediawiki.

Al principio fue trac, después de eso se trasladó a Mediawiki porque era más fácil de usar ...

El principal problema con SVN fue la causa de compartir, teníamos un sistema de autorización para SVN.

— confiq
fuente

2

¿No te refieres a Mediawiki, el motor wiki que usa Wikipedia?

@Martijn, supongo que sí

— Teo Klestrup Röijezon

@Martijn: Sí, editado

— confiq

Prefiero seguir con un wiki en lugar de enviar muchos archivos que no están en curso a un SCM, pero eso tiene más que ver con las preferencias personales. Hay mucho más que puedes hacer con él. Me gusta especialmente Foswiki y su plantilla basada en sitio web / proyecto. Me alegra que alguien haya señalado que decidió usar un wiki debido a problemas :) +1.

— Oeufcoque Penteano

9

Tener algo más que código fuente en un repositorio es algo muy bueno.

Agrupa todos sus recursos y convierte el proyecto en una entidad coherente y centralizada en lugar de una colección dispersa de archivos. Los colaboradores / empleados saben dónde encontrar todo, en lugar de enviar "¿Dónde cambio la documentación para la función x?" correos electrónicos

Querrás mantener las cosas organizadas. Tener un sistema para separar el srcdel imagesdel docs. Siempre puede agregar un .gitignorea un directorio para mantener limpios el repositorio y el historial. Debido a que las confirmaciones de Git están basadas en archivos, * puede desacoplar los cambios de origen de los cambios de documentación tan fuerte como desee.
Como otros han dicho, Git es excelente para el control de versiones de documentación siempre que esté basado en texto.
Estoy completamente de acuerdo; la documentación debe ser versionada junto al código.

Mi credibilidad proviene de ser un usuario de GitHub y contribuir a un proyecto y explorar muchos otros. En mi experiencia, un proyecto completo y unificado es fácil de distinguir de uno medio perdido. Intento contener todos mis proyectos en directorios únicos siempre que sea posible.

* Esto no es del todo exacto, porque hay formas de especificar partes de un archivo para confirmar ( aquí hay un ejemplo ).

— Tyler Wayne
fuente

4

Vine aquí con una pregunta similar. Venimos de un entorno SVN, donde básicamente es obvio mantener todos los materiales relacionados con un proyecto en el mismo repositorio. Debido a la naturaleza de SVN, puede verificar fácilmente partes del repositorio, por lo que si solo necesita el código fuente (por ejemplo, la implementación de un sitio web), no hay problema.

Con Git, las cosas son diferentes. Un proceso de pago siempre está en el nivel raíz, por lo que si desea poner todo en el mismo repositorio, siempre terminará con la misma estructura de directorios. Un enfoque que he encontrado es poner todo en ramas separadas, es decir, tiene ramas de código (que normalmente serían sus ramas maestras, de desarrollo, etc.) y una rama doc, que tiene su propia estructura de directorio separada. Todavía no estoy seguro de que esa sea la mejor idea, pero es una sugerencia que evita el problema que imagino está en la base de su pregunta.

— Eelke Blok
fuente

Las diferentes ramas con estructuras de directorio radicalmente diferentes me huelen muy mal a código. Lo dejaría todo en un repositorio, lo que facilitaría a los contribuyentes agregar más fácilmente una combinación de código y documentación. De hecho, la programación alfabetizada (¡Google eso!) Lo exige.

— tbc0

Al distribuir paquetes, soy partidario del estilo .deb que me permite descargar ejecutables a todos los servidores, mientras que mi cuadro de desarrollo también tiene los paquetes de documentación.

— tbc0

1

Uso un wiki para documentos internos ... obtengo una revisión MÁS acceso prominente / edición fácil. Cuando la documentación no esté sincronizada, actualícela en ese momento. Para la documentación del usuario final, considere una herramienta profesional como Madcap Flare. Usan un dialecto XML para compartir, componer y transformar la documentación.

— Michael Brown
fuente

-1

En el código, los pensamientos suelen estar separados línea por línea. Tiendo a escribir documentación con líneas suaves. Cuando confirmo esos archivos, las líneas tienen un párrafo completo. Eso no es muy útil para leer git diff. Ese es el problema que estaba tratando de resolver cuando busqué en Google y encontré esta página. Gracias a Arne Hartherz por presentarme git diff --word-diff. Puede que te guste git diff --color-wordsaún más.

— tbc0
fuente