O Git deve ser usado para documentação e gerenciamento de projetos? O código deve estar em um repositório separado?

68

Estou iniciando um repositório Git para um projeto de grupo. Faz sentido armazenar documentos no mesmo repositório Git que o código - parece que isso entra em conflito com a natureza do fluxo de revisão do git.

Aqui está um resumo das minhas perguntas:

  • O estilo de revisão do Git será confuso se o código e os documentos forem verificados no mesmo repositório ? Experiências com isso?

  • O Git é adequado para o controle de revisão de documentação?

  • NÃO estou perguntando se um Sistema de Controle de Revisão em geral deve ou não ser usado para documentação - deveria.

Obrigado pelo feedback até agora!

EmpireJones
fonte
Ah, tudo bem ... obrigado pelo esclarecimento. Não vejo por que isso seria um problema, mas não tenho nenhuma experiência pessoal com o GIT (apenas um entendimento teórico); portanto, deixarei alguém com experiência mais direta responder a essa pergunta.
Flimzy
11
Não vejo bem como isso está no tópico. Você está falando sobre documentação de software e se comprometendo com um DVCS
Tim Post
Provavelmente depende da documentação e de suas necessidades. Você precisa de diffs e está em um formato que possa lidar com isso? Se o git fornecer os serviços necessários com certeza. Melhor que ter um sistema de gerenciamento de documentos separado ...
Rig
Se sua documentação estiver em texto sem formatação - tudo bem. Se for um formato binário, você precisa essencialmente de um sistema de controle de versão que entenda o formato binário - esse é o bloqueio do fornecedor em sua forma mais pura.

Respostas:

53

Armazenamos documentação no SVN o tempo todo. De fato, todo o manual do usuário está escrito em LaTeX e armazenado em SVN. Escolhemos o LaTeX especificamente porque é uma linguagem baseada em texto e fácil de mostrar diferenças linha a linha.

Também armazenamos alguns arquivos não formatados em texto, como arquivos .doc do Microsoft Office, planilhas, arquivos .zip, etc., quando necessário ... mas alguns dos benefícios de um RCS são perdidos quando você não consegue ver o valor incremental diffs.

A chave é realmente garantir que sua documentação esteja bem organizada, para que as pessoas possam encontrar (e atualizar) a documentação (e a fonte) quando necessário.

Flimzy
fonte
11
Se você é uma loja da Microsoft, o TortoiseSVN suporta diferenças de linha por linha do MS Office.
Phil
2
A eliminação de formatos binários de documentos tornaria o mundo um lugar melhor. o Como os documentos são em texto simples, também não deve haver nenhum problema real com um DVCS.
Kai Inkinen
Ah, e pela primeira vez ouvi falar sobre o TortoiseSVN e os arquivos de documentos, então marque com +1 um para isso. Gostaria de saber se isso terminará no Tortoise [AnyDVCS] a qualquer momento no futuro.
Kai Inkinen
@ Phil: Como o TortoiseSVN consegue isso? O visualizador de diferenças de documento está integrado ao cliente SVN ou pode ser usado independentemente?
Flimzy
11
Uma opção interessante seria usar o Pandoc para que a maior parte da sua documentação esteja no Markdown, mas os bits cruciais ainda podem usar o TeX. Como ele compila o Markdown para o LaTeX, os resultados são os mesmos. No entanto, isso também permitiria exportá-lo para diferentes formatos e facilitaria a leitura da fonte.
Tikhon Jelvis
22

Bem, depende de qual formato você usa para a documentação. Se é algo baseado em texto, é tudo de bom.

O Git também pode armazenar conteúdo binário e você pode acompanhar as revisões, mas a saída do diff não fará sentido.

Também é possível armazenar a documentação no próprio código, como perldoc pod, java também possui algum formato / anotação para isso.

cstamas
fonte
Concordo que, embora seja possível armazenar documentação não textual, o git se sairá melhor se você armazenar texto. Tem-se falado de um motorista de diff que sabe como diff palavra (ou similar) documentos, mas eu não tenho certeza se ele foi implementado ou não
Sverre Rabbelier
Embora o Word tenha mudado o formato do binário para o XML.
Cledoux
3
@ karategeek6 O formato 'XML' do Word não pode ser lido por humanos. E uma linha de texto não corresponde a uma linha do XML do Word, mesmo em aproximação. Portanto, pode ser binário.
Você pode instruir o Word a salvar sua saída em XML não compactado. Escolha Save Ase selecione em Word XML Document (*.xml)vez do padrão Word Document (*.docx). O XML é bastante complexo, portanto, não há garantia de que as alterações sejam facilmente legíveis, mas pelo menos não serão binárias.
Kyralessa
> mas a saída diff não fará sentido. Incase de diff, poderíamos abrir 2 revisão de lado um documento a lado e comparar por nossos olhos :)
Lucas
14

Não consigo imaginar por que você acha que pode haver um problema ao usar o git, ou qualquer outro sistema de controle de versão, para documentação. Assim como o código-fonte, a documentação deve ter um histórico completo e a capacidade de reverter para uma versão anterior, se necessário. Um sistema de controle de versão é perfeito para isso.


fonte
6
Somente se a documentação estiver em formato de texto. Os blobs binários não se beneficiam totalmente do controle de versão.
2
@ ThorbjørnRavnAndersen: Mesmo assim, a menos que você tenha um sistema de versão específico de binário, provavelmente é melhor manter arquivos binários no Git, em vez de por conta própria.
Tikhon Jelvis
@TikhonJelvis Eu não questionei se é uma boa ideia colocar arquivos binários no git - se eles são os artefatos originais, é. Tente, no entanto, executar "git diff" em documentos do Word.
@ user1249: você pode "exportar" 2 revisão para desktop, dizem my_docs_rev15.docx e my_docs_rev14.docx depois abri-lo lado a lado e comparar por seus olhos e cérebro, não é tão difícil :)
Lucas
14

É claro que o uso de algum tipo de sistema de controle de versão para armazenar documentos não é fácil. A parte mais interessante da pergunta é se é uma boa ideia armazenar documentos no mesmo local como o código-fonte? O possível problema aqui é que pode ser difícil definir privilégios de acesso diferentes para código e documentação nesse caso. E, em muitos casos comerciais, as pessoas precisarão acessar documentos, mas não o código-fonte, como departamentos de marketing ou BA.

Ma99uS
fonte
3
Sim, o aspecto "mesma localização" é uma das partes principais desta pergunta!
O mesmo local é bom se você puder gerenciá-lo, porque evita a necessidade de ter conhecimento tribal (saber para onde procurar) ou a necessidade de procurar onde o material está.
quickly_now
Eles podem não precisar de acesso ao código, mas não deve prejudicar o acesso. Eles não precisam olhar para isso. Segredos geralmente não devem estar no controle de versão.
bdsl
9

Na empresa em que trabalho, colocamos documentação no SVN. No entanto, após alguns conflitos e a necessidade de compartilhá-lo, decidimos movê-lo para o Mediawiki.

No começo, era trac, depois foi para o Mediawiki, porque era mais fácil de usar ...

O principal problema com o SVN foi a causa do compartilhamento, tínhamos um sistema de autorização para o SVN.

confiq
fonte
2
Você não quer dizer Mediawiki, o mecanismo wiki que a Wikipedia usa?
@Martijn, eu diria que assim
Teo Klestrup Röijezon
@Martijn: Sim, editado
confiq
Eu preferiria ficar com um wiki em vez de enviar muitos arquivos que não estão disponíveis para um SCM, mas isso tem mais a ver com preferência pessoal. Há muito mais que você pode fazer com isso. Eu gosto especialmente do Foswiki e do seu site / modelo baseado em projeto. Ainda bem que alguém apontou a decisão de usar um wiki devido a problemas :) +1.
Oeufcoque Penteano
9
  • Ter mais do que apenas código-fonte em um repositório é uma coisa muito boa.

    Ele agrupa todos os seus recursos e transforma o projeto em uma entidade coesa e centralizada, em vez de uma coleção dispersa de arquivos. Os colaboradores / funcionários sabem onde encontrar tudo, em vez de enviar "Onde altero a documentação do recurso x?" e-mails.

    Você vai querer manter as coisas organizadas. Tenha um sistema para separar o srcdo imagesdo docs. Você sempre pode adicionar um .gitignorea um diretório para manter o repositório e o histórico limpos. Como as confirmações do Git são baseadas em arquivos, * você pode separar as alterações de origem das alterações na documentação da maneira que desejar.

  • Como outros já disseram, o Git é ótimo para versionamento de documentação, desde que baseado em texto.

  • Eu concordo completamente; a documentação deve ser versionada ao lado do código.

Minha credibilidade vem de ser um usuário do GitHub e contribuir para um projeto e explorar muitos outros. Na minha experiência, é fácil distinguir um projeto completo e unificado de um projeto que está faltando pela metade. Tento conter todos os meus projetos em diretórios únicos sempre que possível.


* Isso não é muito preciso, porque existem maneiras de especificar partes de um arquivo a serem confirmadas ( aqui está um exemplo ).

Tyler Wayne
fonte
4

Eu vim aqui com uma pergunta semelhante. Nós viemos de um ambiente SVN, onde basicamente é fácil manter todos os materiais relacionados a um projeto no mesmo repositório. Devido à natureza do SVN, você pode facilmente verificar partes do repositório; portanto, se você precisar apenas do código-fonte (por exemplo, uma implantação de site), não há problema.

Com o Git, as coisas são diferentes. Um checkout está sempre no nível raiz, portanto, se você quiser colocar tudo no mesmo repositório, sempre terá a mesma estrutura de diretórios. Uma abordagem que me deparei é colocar tudo em ramificações separadas, ou seja, você tem ramificações de código (que normalmente seriam suas ramificações normais de mestre, desenvolvimento etc.) e uma ramificação de documentos, que possui sua própria estrutura de diretórios separada. Ainda não tenho certeza de que é a melhor ideia, mas é uma sugestão que contorna o problema que imagino estar na base da sua pergunta.

Eelke Blok
fonte
Ramificações diferentes com estruturas de diretório radicalmente diferentes têm um cheiro muito ruim para mim. Eu deixaria tudo em um único repositório, facilitando para os colaboradores a adição mais fácil de uma mistura de código e documentação. De fato, a programação alfabetizada (Google isso!) Exige isso.
precisa saber é
Ao distribuir pacotes, sou parcial com o estilo .deb que permite baixar executáveis ​​para todos os servidores, enquanto minha caixa de desenvolvimento também possui os pacotes de documentação.
precisa saber é
1

Eu uso um wiki para documentos internos ... obtenha revisão além do acesso proeminente / edição fácil. Quando a documentação estiver fora de sincronia, atualize-a imediatamente. Para documentação do usuário final, considere uma ferramenta profissional como o Madcap Flare. Eles usam um dialeto XML para compartilhar, compor e transformar a documentação.

Michael Brown
fonte
-1

No código, os pensamentos são tipicamente separados linha por linha. Costumo escrever documentação com envoltórios de linhas suaves. Quando eu confirmo esses arquivos, as linhas têm um parágrafo inteiro. Isso não é muito útil para ler git diff. Esse é o problema que eu estava tentando resolver quando pesquisei no Google e encontrei esta página. Agradeço a Arne Hartherz por me apresentar git diff --word-diff. Você pode gostar git diff --color-wordsainda melhor.

tbc0
fonte