A documentação gerada deve ser armazenada em um repositório Git?

Quando você usa ferramentas como jsdocs , ele gera arquivos HTML estáticos e seus estilos na sua base de código com base nos comentários no seu código.

Esses arquivos devem ser verificados no repositório Git ou devem ser ignorados com .gitignore?

Ausente qualquer necessidade específica, qualquer arquivo que possa ser criado, recriado, construído ou gerado a partir de ferramentas de construção usando outros arquivos verificados no controle de versão não deve ser registrado. Quando o arquivo for necessário, ele pode ser (re) criado a partir do outro fontes (e normalmente seria como algum aspecto do processo de compilação).

Portanto, esses arquivos devem ser ignorados com .gitignore.

Minha regra é que, quando clono um repositório e pressiono um botão "build", depois de um tempo tudo é criado. Para conseguir isso para a documentação gerada, você tem duas opções: alguém é responsável por criar esses documentos e colocá-los no git, ou documenta exatamente qual software eu preciso na minha máquina de desenvolvimento e certifique-se de pressionar a tecla "build" O botão cria toda a documentação em minha máquina.

No caso da documentação gerada, em que qualquer alteração única que eu faço em um arquivo de cabeçalho deve alterar a documentação, é melhor fazer isso na máquina de cada desenvolvedor, porque desejo a documentação correta o tempo todo, não apenas quando alguém a atualizou. Há outras situações em que gerar algo pode ser demorado, complicado, requer software para o qual você tem apenas uma licença etc. Nesse caso, é melhor dar a uma pessoa a responsabilidade de colocar as coisas no git.

@Urt Simpson: Ter todos os requisitos de software documentados é muito melhor do que eu já vi em muitos lugares.

Esses arquivos não devem ser registrados porque os dados para gerá-los já estão presentes. Você não deseja armazenar dados duas vezes (DRY).

Se você possui um sistema de IC, talvez seja possível criar esses documentos e armazená-los para que os compilem / publiquem em um servidor da web.

Uma vantagem de tê-los em algum repositório (igual ou diferente, de preferência gerado automaticamente) é que você poderá ver todas as alterações na documentação. Às vezes, essas diferenças são mais fáceis de ler do que as diferenças no código-fonte (especificamente se você se importa apenas com alterações de especificação, não com a implementação).

Mas na maioria dos casos, não é necessário tê-los no controle de origem, como as outras respostas explicaram.

Ignorado. Você deseja que os usuários do repositório possam reconstruí-los de qualquer maneira, e isso elimina a complexidade de garantir que os documentos estejam sempre sincronizados. Não há razão para não ter os artefatos construídos agrupados em um só lugar, se você quiser ter tudo em um só lugar e não precisar construir nada. No entanto, os repositórios de fontes não são realmente um bom lugar para fazer isso, embora, como a complexidade prejudique mais do que a maioria dos lugares.

Depende do seu processo de implantação. Mas enviar arquivos gerados para um repositório é uma exceção e deve ser evitado, se possível. Se você puder responder às duas perguntas a seguir com Sim , fazer check-in de seus documentos pode ser uma opção válida:

• Os documentos são um requisito para produção?
• Seu sistema de implantação não possui as ferramentas necessárias para criar os documentos?

Se essas condições forem verdadeiras, você provavelmente está implantando com um sistema legado ou com restrições especiais de segurança. Como alternativa, você pode confirmar os arquivos gerados em uma ramificação de liberação e manter a ramificação principal limpa.

Depende. Se esses documentos:

• Precisa fazer parte do repositório, como o readme.md, então é preferível mantê-los no repositório git. Porque pode ser complicado lidar com essas situações de maneira automatizada.

• Se você não tem uma maneira automatizada de construí-los e atualizá-los, como um sistema de IC, e se destina a ser visto pelo público em geral, é preferível mantê-los no repositório git.

• Leva muito tempo para construí-los, então é justificável mantê-los.

• Destina-se a ser visto pelo público em geral (como o manual do usuário), e leva um tempo considerável para compilar, enquanto seus documentos anteriores se tornam inacessíveis (offline), então é justificável mantê-los no repositório git.

• Destina-se a ser visto pelo público em geral e deve mostrar um histórico de suas alterações / evolução, pode ser mais fácil manter as versões anteriores do documento comprometidas e criar / confirmar a nova vinculada à anterior. Justificável.

• Tem um motivo específico aceito para todo o time ser comprometido, então é justificável mantê-los no repositório git. (Não conhecemos seu contexto, você e sua equipe)

Em qualquer outro cenário, ele deve ser ignorado com segurança.

No entanto, se for justificável mantê-los no repositório git, pode ser um sinal de outro problema maior que sua equipe está enfrentando. (Não possui um sistema de IC ou problemas semelhantes e horríveis de desempenho, enfrentando tempo de inatividade durante a criação, etc.)

Como princípio do controle de versão, apenas "objetos primários" devem ser armazenados em um repositório, não "objetos derivados".

Existem exceções à regra: a saber, quando há consumidores do repositório que exigem os objetos derivados e é razoavelmente esperado que não tenham as ferramentas necessárias para gerá-los. Outras considerações pesam, como é a quantidade de material pesado? (Seria melhor para o projeto conseguir que todos os usuários tivessem as ferramentas?)

Um exemplo extremo disso é um projeto que implementa uma linguagem de programação rara cujo compilador é escrito nessa própria linguagem (exemplos conhecidos incluem Ocaml ou Haskell) Se apenas o código-fonte do compilador estiver no repositório, ninguém poderá construí-lo; eles não têm uma versão compilada do compilador que podem ser executados na máquina virtual, para que possam compilar o código-fonte do compilador. Além disso, os recursos mais recentes da linguagem são imediatamente usados ​​na própria fonte do compilador, para que seja sempre necessária a versão mais recente do compilador para compilá-lo: um executável do compilador de um mês, obtido separadamente, não compilará o código atual porque o código usa recursos de idioma que não existiam há um mês. Nessa situação, a versão compilada do compilador quase certamente precisa ser verificada no repositório e mantida atualizada.