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

62

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

Aqui está um resumo da (s) minha (s) pergunta (s):

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

  • O Git é um bom ajuste para o controle de revisão de documentação?

  • Eu estou NÃO perguntando se um sistema de controle de revisão em geral deveria ou não ser usado para documentação - deveria.

Obrigado pelo feedback até agora!

    
por EmpireJones 17.06.2011 / 08:36
fonte

9 respostas

51

Armazenamos a documentação no SVN o tempo todo. Na verdade, todo o manual do usuário está escrito em LaTeX e armazenado no SVN. Nós escolhemos o LaTeX especificamente porque é uma linguagem baseada em texto e fácil de mostrar os diffs linha por linha.

Também armazenamos alguns arquivos formatados sem 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 os diffs incrementais.

A chave é realmente certificar-se de que sua documentação esteja bem organizada, para que as pessoas possam encontrar (e atualizar) a documentação (e a fonte) quando precisarem.

    
por 17.06.2011 / 08:46
fonte
22

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

O Git também pode armazenar conteúdo binário e você pode rastrear 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 pod perldoc, o java também tem algum formato / anotação para isso.

    
por 17.06.2011 / 08:49
fonte
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 isso for necessário. Um sistema de controle de versão é perfeito para isso.

    
por 17.06.2011 / 09:31
fonte
13

É claro que usar algum tipo de sistema de controle de versão para armazenar documentos é um nobrainer. A parte mais interessante da questão é se é uma boa ideia armazenar documentos na mesma localização como 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 de negócios, as pessoas precisarão acessar os documentos, mas não o código-fonte, como departamentos de marketing ou de administração pública.

    
por 17.06.2011 / 14:25
fonte
9

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

A princípio foi trac, depois disso mudou para o Mediawiki porque era mais fácil de usar ...

O principal problema com o SVN foi a causa de compartilhamento que tivemos o sistema de autorização para o SVN.

    
por 17.06.2011 / 13:04
fonte
6
  • Ter mais do que apenas código-fonte em um repositório é uma coisa muito boa.

    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 posso alterar a documentação do recurso x?" e-mails.

    Você vai querer manter as coisas organizadas. Ter um sistema para separar o src do images do docs . Você sempre pode adicionar um .gitignore a 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 dissociar alterações de origem das alterações da documentação tão strongmente quanto desejar.

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

  • Eu concordo completamente; 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, um projeto completo e unificado é fácil de dizer de um meio ausente. Eu tento conter todos os meus projetos dentro de diretórios individuais sempre que possível.

* Isso não é muito preciso, porque existem maneiras de especificar partes de um arquivo a ser confirmado ( aqui está um exemplo ).     
por 08.09.2012 / 00:47
fonte
4

Eu vim aqui com uma pergunta semelhante. Nós viemos de um ambiente SVN, onde basicamente é simples 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 implementação do site), isso não é problema.

Com o Git, as coisas são diferentes. Um check-out está sempre no nível raiz, portanto, se você quiser colocar tudo no mesmo repositório, sempre terminará com 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. Não tenho certeza, mas essa é a melhor ideia, mas é uma sugestão que contorna o problema que imagino estar na base da sua pergunta.

    
por 15.03.2012 / 12:17
fonte
1

Eu uso um wiki para documentos internos ... recebo revisão PLUS acesso proeminente / edição fácil. Quando a documentação estiver fora de sincronia, atualize-a imediatamente. Para a documentação do usuário final, considere uma ferramenta profissional como Flare maluco Eles usam um dialeto XML para compartilhar , compondo e transformando a documentação.

    
por 17.06.2011 / 19:52
fonte
-1

No código, os pensamentos são normalmente separados linha por linha. Eu costumo escrever documentação com quebra de linha suave. Quando eu comprometo esses arquivos, as linhas são um longo parágrafo. Isso não é muito útil para ler em git diff . Esse é o problema que eu estava tentando resolver quando eu pesquisei e encontrei esta página. Obrigado a Arne Hartherz por me apresentar a git diff --word-diff . Você pode gostar de git diff --color-words ainda melhor.

    
por 07.11.2015 / 21:51
fonte