search

menthorlabs / menthor

Plataforma gratuita e open-source de ensino de programação
https://menthor.io/
Apache License 2.0
575 stars 34 forks source link

Criação de Guia de Contribuição e Comunicação em Português #23

Closed the-physicist closed 11 months ago

the-physicist commented 1 year ago

Olá humanos,

Gostaria de propor a criação de um Guia de Contribuição para o projeto. Um Guia de Contribuição é essencial para facilitar o processo de integração de novos colaboradores e para garantir que todos estejam na mesma página em relação aos padrões e práticas de desenvolvimento do projeto, possibilitando facilitar até a manutenção.

Motivação:

  1. Comunicação em Português: Considerando que nosso projeto visa oferecer cursos gratuitos na área de TI, acredito que a comunicação em português seja mais acessível para iniciantes e para a maioria dos nossos colaboradores. Isso permitirá que todos compreendam as discussões e as contribuições de forma mais eficaz.

  2. Padrão de Comunicação: Precisamos estabelecer que a comunicação será predominantemente em português (commits, discussões, repositório etc), mas as linhas de código e os comentários poderiam ser em inglês até para servir de prática.

  3. Padrão de Estilo: Um padrão de estilo é fundamental para manter a consistência em todo o código, na estrutura dos diretórios, nos commits e nas mensagens de commit. Isso tornará o projeto mais fácil de manter e ajudará a evitar problemas causados por diferenças de estilo ou na comunicação.

O que proponho:

  1. Especificar que a comunicação principal será em português.

  2. Estabelecer um padrão de estilo para o código, incluindo formatação, nomenclatura de variáveis, estrutura de diretórios e mensagens de commit. Isso será detalhado no Guia de Contribuição criado por nós (ou se basear em algum existente).

O que acham?

BernardoSM commented 12 months ago

Fala @the-physicist adorei a ideia, só o item 2 da proposta que não entendi direito. Hoje em dia o "estilo do código" é gerenciado pelo prettier/eslint, as mensagens de commit pra mim não tem tanta diferença ser em inglês ou português...

Agora eu concordo que deveríamos padronizar a comunicação de issues, discussions, etc. Como o projeto é voltado 100% para o público nacional, deveríamos sim mantê-lo tudo em português.

Você tem algum exemplo de Guia de Contribuição que achou legal? Gostaria de saber mais sobre isso, obrigado!!

the-physicist commented 12 months ago

Salve, @BernardoSM!

Então, eu pensei em coisas mais simples como criar as tags (fix, feat, style, refactor, test, docs, etc); definir se deve ser maiúscula ou minúsculas (FIX, Fix ou fix); se será em português ou inglês; ressaltar a importância de fazer commits pequenos; quando usar ou não descrição além do título....sabe? Definir coisas nesse sentido.

Penso que isso ajudaria porque além de criar um padrão que facilita a leitura/manutenção, também remove essa responsabilidade na decisão de quem vai contribuir. Por exemplo, eu levei muito tempo para decidir se eu deveria falar em inglês ou português; se eu deveria abrir Issue ou fazer PR diretamente; se eu deveria usar as tags...fiquei em dúvida porque vi várias pessoas fazendo isso de formas diferentes. E iniciantes, que acredito serem o público-alvo do projeto, provavelmente vão ter dúvidas semelhantes.

Sobre oo Guia de Contribuição, eu pensei em seguir algumas convenções de boas práticas de commits. Poderíamos usar uma combinação do conventional commits com o gitmoji, por exemplo.

Eu posso fazer uma primeira versão e apresentar aqui para vocês, se quiser. Só me avisa que eu faço!

Shnrqpdr commented 12 months ago

Eu não gosto muito do gitmoji por achar que polui um pouco a mensagem, mas sem dúvidas o conventional commits ajudaria bastante, na minha opinião é até estéticamente mais bonito escrever as mensagens seguindo os conventional commits.

BernardoSM commented 11 months ago

Opa @the-physicist você pode fazer uma versão somente com conventional commits? Também acho que o gitmoji polui um pouco como o @Shnrqpdr comentou.

Obrigado!

BernardoSM commented 11 months ago

Ótimo trabalho @mikaelhadler . Ei @the-physicist vou fechar essa issue mas se tiver mais algo que vê sentido em melhorar, pode abrir novamente.

the-physicist commented 11 months ago

Fala, @BernardoSM.

Então, dei uma olhada e algumas coisas me deixaram confuso. Eu não entendi porque os arquivos de template possuem apenas links de sessão com o conteúdo comentado. Tô em dúvida se é assim porque está esperando alguém contribuir ou se é o template finalizado de fato. E aparentemente esse modelo de template não é mais recomendado pelo GitHub, talvez seja interessante atualizar.

image

Eu também não entendi porque o arquivo CONTRIBUTING.md é curtinho assim sem revelar os detalhes do guia. É para redirecionar para os respectivos templates de issue e pull request? Não é mais interessante detalhar tudo no mesmo arquivo CONTRIBUTING.md?

São questões realmente para eu entender como o @mikaelhadler pensou em estruturar o guia.

Quando eu levantei esse ponto do guia, pensei apenas em um arquivo de contribuição detalhando os padrões de commit, boas práticas do projeto e enfatizando o uso do português. Além disso, pensei também em adicionar parte disso no README.md. Não pensei em templates em si (o que é uma boa ideia, aliás). Eu acho que o template faz sentido porque assim que a pessoa entra nas páginas de issue ou pull request ela automaticamente vê a mensagem para ler o guia, assim: image

Segue alguns exemplos de Guia de Contribuição que eu pensei para o projeto:

Esse aqui parece estar no formato que o Mikael pensou. E eu gosto dele.

Aguardo a decisão as considerações de vocês para submeter minhas contribuições.

Abraço!

mikaelhadler commented 11 months ago

Olá @the-physicist, eu entendo o ponto que você levantou sobre o template de abertura de issues. Talvez fosse mais claro para os usuários se as informações não fossem apenas comentários, mas estivessem visíveis. O que você acha?

E aparentemente esse modelo de template não é mais recomendado pelo GitHub, talvez seja interessante atualizar.

Eu não tenho certeza a que modelo você se refere nesta seção. Poderia especificar qual arquivo não está dentro do padrão?

Eu também não entendi porque o arquivo CONTRIBUTING.md é curtinho assim sem revelar os detalhes do guia. É para redirecionar para os respectivos templates de issue e pull request? Não é mais interessante detalhar tudo no mesmo arquivo CONTRIBUTING.md?

Minha intenção ao simplificar as informações era criar um ponto de partida flexível e permitir que os contribuidores acrescentassem o que achassem relevante. Se achar que alguma informação importante está faltando, seria ótimo se você pudesse abrir um pull request e discutir as adições necessárias.

Fiquei realmente impressionado com as observações que você fez, @the-physicist. Acredito que seria uma ótima primeira contribuição se você pudesse criar um pull request com essas sugestões e correções. Se estiver com pouco tempo, também é possível abrir uma issue e atribuí-la a mim, e eu contribuirei assim que possível.

Caso tenha passado algo a mais despercebido, vamos discutindo abraço :]

the-physicist commented 11 months ago

Olá, @mikaelhadler.

Peço desculpas se te ofendi de alguma forma, eu realmente só não tinha entendido se sua contribuição estava finalizada ou era a base para suportar novas contribuições. Agora eu entendi que os templates são arquivos que surgem quando alguém abre uma nova issue ou PR. Eu inicialmente achei que era apenas um arquivo markdown, por isso questionei a formatação deles.

Sobre o Guia de Contribuição, acabei de enviar a PR #29 com a forma que imaginei o arquivo CONTRIBUTING. Também criei um Código de Conduta e fiz a atualização do README para a nova seção.

Se vocês gostarem eu atualizo os arquivos de template em breve.

mikaelhadler commented 11 months ago

Fala @the-physicist relaxa, de forma alguma você me ofendeu, talvez a forma como eu respondi tenha dado a entender isso, se for isso me desculpe também :heart:, amanhã pela tarde já faço a revisão.