diff --git a/cp_07.Rmd b/cp_07.Rmd index a085eda9a65885b5e12e3419eec8c8479f76b879..015e655768a5f70a89126416b3ee3f672b042727 100644 --- a/cp_07.Rmd +++ b/cp_07.Rmd @@ -71,30 +71,87 @@ mesmo. Essas mensagens também aparecerão no git log do projeto, por isso é essencial que sejam bem escritas, de forma clara e sigam um padrão. -Algumas **regras de ouro** para que um projeto versionado com git -seja bem sucedido são: +Algumas **regras de ouro**, que são convenções gerais, para que um projeto +versionado com git seja bem sucedido são: -- Faça commits regularmente: isso faz com que as mudanças de código +- **Faça commits regularmente**: isso faz com que as mudanças de código entre um commit e outro sejam menores, tornando mais fácil para todos acompanhar as alterações; -- Não faça commits de trabalhos pela metade: faça um commit apenas + +- **Não faça commits de trabalhos pela metade**: faça um commit apenas quando tiver finalizado o que estava propondo. Isso irá forçar você a deixar o trabalho em pedaços menores, e por consequência realizar -commits regularmente. -- Teste antes de fazer um commit: resista à tentação de fazer um commit +commits regularmente; + +- **Teste antes de fazer um commit**: resista à tentação de fazer um commit que você pensa que está completo. Teste toda a sua realização para -ter certeza de que não causará um efeito colateral no projeto. -- Escreva boas mensagens de commit: seja claro e objetivo ao escrever +ter certeza de que não causará um efeito colateral no projeto; + +- **Escreva boas mensagens de commit**: seja claro e objetivo ao escrever as mensagens de commit. No entanto, tome cuidado para não ser vago, ou escrever apenas `mudança`, `mais mudanças`, etc. Se uma mensagem curta for suficiente, use `git commit -m 'Mensagem'`, mas lembre-se de ser informativo sobre a alteração realizada, para ser útil para todos do projeto. +Existem outras convenções estabelecidas sobre como escrever mensagens +de commit contextualizadas, baseadas nas mensagens geradas por mensagens +de funções do próprio git. Estas convenções podem resumidas nas 7 regras +que são convenções globais: + +1.**Separe o tÃtulo do corpo do texto com uma linha em branco**: por padrão, +a primeira linha é o tÃtulo do commit, e deve ser uma mensagem curta. +Ao deixar uma linha em branco, é permitido escrever uma mensagem de +qualquer tamanho, detalhando melhor as modificações feitas. +Dessa forma, quando `git log` for executado, toda a mensagem de commit +aparecerá, enquanto que `git log --oneline` mostrará apenas o tÃtulo do +commit. + +2.**Limite a linha de tÃtulo em 50 caracteres**: isso faz com que o +colaborador pense mais para escrever uma mensagem mais informativa. +Se a mensagem for uma única linha (`git commit -m`), então esse limite +pode se estender para 72 caracteres. + +3.**Capitalize a mensagem**: em todas as mensagens de commit comece com +letra maiúscula, tanto se for tÃtulo, corpo da mensagem, ou apenas +uma mensagem de uma única linha. + +4.**Não termine os commits com ponto**: principalmente se for o tÃtulo +de uma mensagem de commit mais longa. Espaço é valioso quando se temos +no máximo 50 ou 72 caracteres. + +5.**Use o modo imperativo**: no tÃtulo de commits longos ou em mensagens +de commits únicas. O modo imperativo significa "falar ou escrever como +se estivesse dando uma ordem ou uma instrução". Seja direto e objetivo, +e escreva no presente. Exemplos de mensagens no impertativo: + +- Adiciona versão final + +- Remove funções precipitadas + +Algumas mensagens no modo **não** imperativo são: + +- Corrigindo o erro + +- Mudando a função + +- Mais correções para mais funções + +6.**Limite o corpo da mensagem em 72 caracteres**: ao escrever uma mensagem +de commit mais longa, após o tÃtulo devemos manter o corpo da mensagem +com no máximo 72 carateres. + + +7.**Use o corpo da mensagem para explicar "o que" e "porque", e não "como"**: contextualize o que você fez e o motivo. Na maioria dos casos você pode +deixar de fora como você fez as modificações, pois o código alterado já +deverá ser auto-explicativo. + + +#### Esqueleto do tópico -- **Repositórios: nÃveis de acesso, adicionar colaboradores, configuração -inicial do repositório** +- Repositórios: nÃveis de acesso, adicionar colaboradores, configuração +inicial do repositório -- **Commits: convenções gerais** e *especÃficas* +- Commits: convenções gerais especÃficas ## 2.Modelos de fluxos de trabalho diff --git a/cp_07.md b/cp_07.md index 20d4f6deabe7b1947b9f0495d9c2945bd00daf54..0797fb0e871270b39f10af03c45aba6f3ccbb6d4 100644 --- a/cp_07.md +++ b/cp_07.md @@ -66,30 +66,87 @@ mesmo. Essas mensagens também aparecerão no git log do projeto, por isso é essencial que sejam bem escritas, de forma clara e sigam um padrão. -Algumas **regras de ouro** para que um projeto versionado com git -seja bem sucedido são: +Algumas **regras de ouro**, que são convenções gerais, para que um projeto +versionado com git seja bem sucedido são: -- Faça commits regularmente: isso faz com que as mudanças de código +- **Faça commits regularmente**: isso faz com que as mudanças de código entre um commit e outro sejam menores, tornando mais fácil para todos acompanhar as alterações; -- Não faça commits de trabalhos pela metade: faça um commit apenas + +- **Não faça commits de trabalhos pela metade**: faça um commit apenas quando tiver finalizado o que estava propondo. Isso irá forçar você a deixar o trabalho em pedaços menores, e por consequência realizar -commits regularmente. -- Teste antes de fazer um commit: resista à tentação de fazer um commit +commits regularmente; + +- **Teste antes de fazer um commit**: resista à tentação de fazer um commit que você pensa que está completo. Teste toda a sua realização para -ter certeza de que não causará um efeito colateral no projeto. -- Escreva boas mensagens de commit: seja claro e objetivo ao escrever +ter certeza de que não causará um efeito colateral no projeto; + +- **Escreva boas mensagens de commit**: seja claro e objetivo ao escrever as mensagens de commit. No entanto, tome cuidado para não ser vago, ou escrever apenas `mudança`, `mais mudanças`, etc. Se uma mensagem curta for suficiente, use `git commit -m 'Mensagem'`, mas lembre-se de ser informativo sobre a alteração realizada, para ser útil para todos do projeto. +Existem outras convenções estabelecidas sobre como escrever mensagens +de commit contextualizadas, baseadas nas mensagens geradas por mensagens +de funções do próprio git. Estas convenções podem resumidas nas 7 regras +que são convenções globais: + +1.**Separe o tÃtulo do corpo do texto com uma linha em branco**: por padrão, +a primeira linha é o tÃtulo do commit, e deve ser uma mensagem curta. +Ao deixar uma linha em branco, é permitido escrever uma mensagem de +qualquer tamanho, detalhando melhor as modificações feitas. +Dessa forma, quando `git log` for executado, toda a mensagem de commit +aparecerá, enquanto que `git log --oneline` mostrará apenas o tÃtulo do +commit. + +2.**Limite a linha de tÃtulo em 50 caracteres**: isso faz com que o +colaborador pense mais para escrever uma mensagem mais informativa. +Se a mensagem for uma única linha (`git commit -m`), então esse limite +pode se estender para 72 caracteres. + +3.**Capitalize a mensagem**: em todas as mensagens de commit comece com +letra maiúscula, tanto se for tÃtulo, corpo da mensagem, ou apenas +uma mensagem de uma única linha. + +4.**Não termine os commits com ponto**: principalmente se for o tÃtulo +de uma mensagem de commit mais longa. Espaço é valioso quando se temos +no máximo 50 ou 72 caracteres. + +5.**Use o modo imperativo**: no tÃtulo de commits longos ou em mensagens +de commits únicas. O modo imperativo significa "falar ou escrever como +se estivesse dando uma ordem ou uma instrução". Seja direto e objetivo, +e escreva no presente. Exemplos de mensagens no impertativo: + +- Adiciona versão final + +- Remove funções precipitadas + +Algumas mensagens no modo **não** imperativo são: + +- Corrigindo o erro + +- Mudando a função + +- Mais correções para mais funções + +6.**Limite o corpo da mensagem em 72 caracteres**: ao escrever uma mensagem +de commit mais longa, após o tÃtulo devemos manter o corpo da mensagem +com no máximo 72 carateres. + + +7.**Use o corpo da mensagem para explicar "o que" e "porque", e não "como"**: contextualize o que você fez e o motivo. Na maioria dos casos você pode +deixar de fora como você fez as modificações, pois o código alterado já +deverá ser auto-explicativo. + + +#### Esqueleto do tópico -- **Repositórios: nÃveis de acesso, adicionar colaboradores, configuração -inicial do repositório** +- Repositórios: nÃveis de acesso, adicionar colaboradores, configuração +inicial do repositório -- **Commits: convenções gerais** e *especÃficas* +- Commits: convenções gerais especÃficas ## 2.Modelos de fluxos de trabalho