Padrões de commits e/ou PR

[johnazedo]

Bom dia, pessoal.

Como na Milestone 1 tem como uma das metas a padronização de commits, venho propor algumas regras que uso para contribuir em projetos com outros programadores. Costumo colocar essa regras no arquivo CONTRIBUTING.md.

Caso seja interessante, podemos ver uma adaptação desse arquivo, ou a criação de um novo que seja mais coerente com a política do projeto.

[CarlosZiegler]

Ola @johnazedo acredito que outra boa padronizacao seria de BUG reportadas, colocar padrao como:

Descreva o bug
.....

Reproduzir
Passos para reproduzir o comportamento:
....

Link Codesandbox ( caso necessario )
....

Comportamento esperado
....

Capturas de tela
....

Contexto adicional
...

Acredito que se desde o inicio adotar-mos um padrao e documentar ficara mais facil a compreensao de todos os envolvidos.

[CarlosZiegler]

Encontei isso aqui na outra Issue acho que vale a pena trocar uma ideia sobre isso. @thenriquedb
#4 (comment)

[johnazedo]

Boa, não tinha pensado nesse caso. Vou refatorar o arquivo e volto a postar aqui.

[johnazedo]

Reportando Bugs

Na hora da criação de reporte de bugs, é importante descrever com detalhes o erro e onde você o encontrou, para isso você terá que informar alguns infomações importantes, como:

Tópico	Descrição	Opcional
Resumo	Tente resumir em uma frase o problema com o bug para ser usado no título.	❌
Descrição	Na descrição tente ser o mais detalhado possível sobre o erro.	❌
Reprodução	Tente informar o caminho que você seguiu para chegar no erro, isso é importante pois facilitará outros desenvolvedores a identificarem o bug e resolver.	❌
Comportamento esperado	Detalhe o que você esperava acontecer quando o erro apareceu.	❌
Captura de tela	Para ficar mais fácil, você pode enviar capturas de sua tela para apresentar melhor o problema encontrado	✔️
Soluçao	Você pode descrever uma possível solução para o problema	✔️

Exemplo de uso

# Problema na criação do usuário

Quando vou cadastrar um usuário e erro algum campo, é apontado um erro no topo do formulário mas não especifica em qual campo o erro aconteceu.

## Como reproduzir?

- Acesse tabnews.com.br/cadastro;
- Preencha todo o formulário mas deixe um campo errado;
- Envie o formulário.

## Comportamento esperado?

Estava esperando que o formulário mostrasse qual campo eu errei deixando ele em vermelho e o porquê que eu errei, informando a mensagem do problema.

[johnazedo]

@CarlosZiegler aqui está o arquivo completo CONTRIBUTING.md

[devinvestidor]

O que acham de adicionarmos o commitlint + husky + commitizen para nos ajudar nessa tarefa?

[johnazedo]

Branchs

As branchs que deve-se criar tem que conter um prefixo apontando qual classificação principal da mesma.

Prefixo	Descrição
feature	Implementação de nova funcionalidade no sistema.
fix	Conserto de erros apresentados pelo software ou melhoria no cõdigo.
docs	Modificação nos documentos do programa.
style	Branch destinada apenas para mudanças no template.
test	Branch destinada para criação de testes nas novas features.

Além disso, deve-se sempre destinar uma branch a uma ou mais issues, ou seja, para que uma branch ser criada precisa de criar uma isseu com um problema a solucionar.
Lembre-se que sempre se deve colocar o número da issue na título da branch.

Exemplo de uso

feature/#12
feature-create-users-28
fix-23
...

[johnazedo]

Commits

Esses marcadores são importantes para diminuir a quantidade de arquivos de cada commit, permitindo ao gestor ou programador-chefe a rápida verificação na mudança do código.

Prefixo	Descrição
feature	Arquivos com implementação de nova funcionalidade no sistema.
fix	Conserto de erros apresentados pelo software ou melhoria no cõdigo.
docs	Modificação nos documentos do programa, removendo ou adicionando comentários no código.
style	Modificações principais nos templates do site.
test	Criação de testes nas novas features.

Deve-se sempre colocar os marcadores na descrição do commit.

Exemplo de uso

git commit -m "feature: Create user"
git commit -m "fix: Fixing DNS error"
git commit -m "test: Creating tests to profile views"

[johnazedo]

Pull Request

Todos os pull requests serão feitos pela interface web do github. Deve-se sempre destinar a algum review, ou seja, sempre marcar outra pessoa do time para verificar seu código.

A estrutura do pull request deve ter como título a modificação mais relevante feita naquela branch, a issue referente apontada no corpo do PR, uma descrição mais aprofundada das modificações e sugestões de possíveis melhorias.

Exemplo de uso

# Criação de usuário finalizada

A funcionalidade de criação de usuário está completa, juntamente com testes e a documentação da feature.

Resolved #12

## O que foi feito?
- Página de cadastro;
- Middleware para salvar logs de visitantes;
- Documentação de caso de uso e de fluxo feitos;
- Testes E2E feitos para essa funcionalidade.

## Sugestões
- Modificar banco de dados para incluir CPF na próxima versão

[filipedeschamps]

Que thread sensacional!!!!! 😍 Eu não tinha nem considerado os padrões de templates para Issues ou Branches 😂

Uma sugestão para avançarmos: separar uma das coisas propostas por essa issue (padrão de commits) e atacar primeiro ela com as soluções propostas pelo @karanalpe para já pegar erros no pre-commit hook, e engatar também essas coisas nos checks aqui do Github. Isso nos vai dar a garantia que navegar pelo histórico de commits vai ser algo sano.

Das outras sugestões, lendo a thread me veio uma sensação que, para o estágio atual do projeto (que está em super beta privado e num ambiente controlado), o saldo de toda essa padronização não vai ser positivo. Então minha sugestão é fazermos isso num timing melhor, que pode ser logo antes de abrirmos o repositório de forma pública para a comunidade. O que acham? Daí a gente traz todas essas regras de contribuições através de templates para Issues e PRs e que com certeza vão fazer toda diferença quando o projeto receber o ruído do mundão lá fora.

E quem pode nos ajudar a implementar no repositório as regras de commit, junto aos hooks e checks aqui do Github?

[rodrigoKulb]

@filipedeschamps e @johnazedo o que acham de criar um (rules.md ou good-habits.md) Com algumas boas práticas de Commits, Branchs etc...?
Assim podemos sempre atualizar esse arquivo "padrão" conforme evolução do projeto, finalizando essa Issues.

[johnazedo]

@rodrigoKulb e @filipedeschamps Acho a ideia ótima, deixamos isso com sugestões até o repositório ir para sua forma pública. Posso escrever um documento para servir como modelo e não como regra em si.

[brunofamiliar]

Reportando Bugs

Na hora da criação de reporte de bugs, é importante descrever com detalhes o erro e onde você o encontrou, para isso você terá que informar alguns infomações importantes, como:

Tópico Descrição Opcional
Resumo Tente resumir em uma frase o problema com o bug para ser usado no título. ❌
Descrição Na descrição tente ser o mais detalhado possível sobre o erro. ❌
Reprodução Tente informar o caminho que você seguiu para chegar no erro, isso é importante pois facilitará outros desenvolvedores a identificarem o bug e resolver. ❌
Comportamento esperado Detalhe o que você esperava acontecer quando o erro apareceu. ❌
Captura de tela Para ficar mais fácil, você pode enviar capturas de sua tela para apresentar melhor o problema encontrado ✔️
Soluçao Você pode descrever uma possível solução para o problema ✔️

Exemplo de uso

# Problema na criação do usuário

Quando vou cadastrar um usuário e erro algum campo, é apontado um erro no topo do formulário mas não especifica em qual campo o erro aconteceu.

## Como reproduzir?

- Acesse tabnews.com.br/cadastro;
- Preencha todo o formulário mas deixe um campo errado;
- Envie o formulário.

## Comportamento esperado?

Estava esperando que o formulário mostrasse qual campo eu errei deixando ele em vermelho e o porquê que eu errei, informando a mensagem do problema.

Em relação a isso, o que vocês acham de adicionar mais duas descrições?

Ambiente

Descrever qual ambiente ocorre o erro (navegador chrome, opera, firefox, edge..., servidor).

URL da fonte

Informar endpoint onde foi identificado o erro

[brunofamiliar]

Pull Request

Todos os pull requests serão feitos pela interface web do github. Deve-se sempre destinar a algum review, ou seja, sempre marcar outra pessoa do time para verificar seu código.

A estrutura do pull request deve ter como título a modificação mais relevante feita naquela branch, a issue referente apontada no corpo do PR, uma descrição mais aprofundada das modificações e sugestões de possíveis melhorias.

Exemplo de uso

# Criação de usuário finalizada

A funcionalidade de criação de usuário está completa, juntamente com testes e a documentação da feature.

Resolved #12

## O que foi feito?
- Página de cadastro;
- Middleware para salvar logs de visitantes;
- Documentação de caso de uso e de fluxo feitos;
- Testes E2E feitos para essa funcionalidade.

## Sugestões
- Modificar banco de dados para incluir CPF na próxima versão

Essa questão eu acho sensacional e fundamental para o projeto. Com o code review, além de manter o código "bem codado", teremos uma grandiosa oportunidade de aprender com outras pessoas, e olhar pra nossas entregas em diferentes pontos de vista. Isso vai dar um UP em nosso conhecimento concerteza

[rodrigoKulb]

@johnazedo acredito que pode criar essa PR com o arquivo CONTRIBUTING.md com uma pequena introdução informando que o objetivo desse arquivo é deixar um modelo de boas práticas para melhorar a interatividade e organização entre os colaboradores do projeto.

Assim já podemos ir evoluindo esse arquivo até liberar ao publico externo.

Edit: Se o @filipedeschamps achar melhor deixar para o futuro, devemos finalizar essa Issue e adicionar no grupo repescar

[filipedeschamps]

Turma, fiz o PR #80 que implementa parcialmente o que foi descrito nessa issue 👍 eu marquei ela com a tag repescar, pois sugiro reduzir o escopo apenas para as mensagens de commit e deixar a padronização de outros conteúdos para quando formos abrir o repositório publicamente 👍