Guia de contribuição #219

eberfreitas · 2018-06-10T05:02:23Z

Proposta de guia de contribuição levando em consideração as discussões da issue #201 bem como o PR #211 e seus comentários.

Também contém sugestão de conteúdo que atente à issue #218.

Mudanças no README apontando para o guia, dentre outros pequenos ajustes.

Refs #201 - Adiciona o arquivo CONTRIBUTING.md; - Revisiona o README.md apontando para o guia e outros ajustes.

Refs #201 Permite a utilização de templates para a criação de bug reports e outros assuntos com integração à interface do GitHub.

farribeiro · 2018-06-10T13:09:17Z

Poderia ter reaproveitado a PR #211 que está aberta

MarceloCajueiro

Ótimo!

MarceloCajueiro · 2018-06-10T18:33:27Z

@williamespindola pode dar sua opinião para fazermos o merge?

williamespindola · 2018-06-10T23:23:27Z

Muita coisa ja esta aqui, mas par complementar vale a leitura https://help.github.com/articles/setting-up-your-project-for-healthy-contributions/

williamespindola

Gostei bastante, ele tem um caráter bem humano e informativo, o contrário do que eu propus que foi 100% técnico. :D
Mas senti falta de pontos técnicos, vou lista-los abaixo:

Release Cycle ou Semver. Esta em definição ainda seu sei, mas não é informado aqui;
Testes, sei que ainda não temos uma boa cobertura, mas se alguém vai contribuir precisa saber que precisa colocar, será uma condição sine qua non para seu PR ser aceito. E também nos polpa tempo no review, pois garante a funcionalidade.
Não informa sobre documentação, se alguém adicionar uma feature nova precisa documentar isto.
Um pull request por feature - Se você quiser fazer mais de uma coisa, envie várias pull requests.
Se você tivesse que fazer vários commits intermediários enquanto desenvolvendo, or favor execute um squash antes de submeter. Com isto não vão precisar perguntar como fazer.

É isto, parabéns pelo trabalho, vamos em frente \o/

williamespindola · 2018-06-10T23:30:27Z

.github/ISSUE_TEMPLATE/bugs.md

@@ -0,0 +1,19 @@
+---


Legal pedir o ambiente aqui, algo assim:

## Seu ambiente Inclua o máximo de informações relevantes sobre o ambiente que você encontrou o bug e como reproduzir isto. - Versão usada (e.g. PHP 5.6, HHVM 3, I-educar 1.0): - Sistema operacional e versão (e.g. Ubuntu 16.04, Windows 7): - Navegador e versão (e.g Chrome 35.9.9.9) - ... - ...

Gosto! Vou colocar.

williamespindola · 2018-06-10T23:33:36Z

.github/ISSUE_TEMPLATE/outros.md

@@ -0,0 +1,9 @@
+---


Não entendi muito bem este template, ele vai ser para features? Se sim poderia ter algumas informações como:

Contexto

Porque esta alteração é importante? Como você usaria isto?

Como esta alteração pode beneficiar outros usuários?

Possível implementação

Não obrigatório, mas sugira uma idéia de como isto poderia ser implementado.

Esse template vai ser pra todo o resto que não é bug report, então engloba features, refactors, etc. Achei que não valeria a pena fazer um template específico pra cada uma dessas coisas e espera-se que a pessoa tenha lido o guia antes de preencher a issue. Mas o texto que você usou é bem flexível e acho que pode ser aproveitado :) Vou tentar integrar da melhor forma possível.

williamespindola · 2018-06-10T23:35:17Z

CONTRIBUTING.md

+
+Não se aplica.
+
+```


Colocando o template dentro de .github/ISSUE_TEMPLATE ele automagicamente vai aparecer dentro do formulário qual alguém for criar uma issue, precisamos deixar aqui também?

Não entendi mto bem a pergunta, mas esse esquema funciona +/- assim:

https://github.com/TryGhost/Ghost/issues/new/choose

Eu nunca usei realmente e espero q tenha feito certo :P

Animal isso!

williamespindola · 2018-06-10T23:37:50Z

CONTRIBUTING.md

+
+Outra ótima forma de contribuir é indicando melhorias ao código do i-Educar e em como ele está estruturado. Se você tem qualquer ideia de como podemos melhorar alguma abordagem na solução de problemas, refatoração de código, melhoria em algum recurso ou qualquer outra coisa relacionada, siga estes passos:
+
+1. Certifique-se de que sua ideia já não esteja sendo abordada em nosso [roadmap](./README.md#roadmap-de-tecnologia);


O Roadmap poderia ficar na wiki, um exemplo https://github.com/Respect/Validation/wiki/Respect%5CValidation-1.1
No readme é legal ter informações sobre o que é o projeto e como você pode instalar, executar, testar e informações legais.

Criei um planejamento a logo prazo aqui: https://github.com/portabilis/i-educar/wiki/Planejamento-T%C3%A9cnico

No readme pode ter esse de curso prazo e linkar o de longo prazo.

williamespindola · 2018-06-10T23:39:29Z

CONTRIBUTING.md

+   1. Você realmente esta propondo uma ideia só ou um conjunto de ideias?
+   2. Qual é o problema que sua ideia resolve?
+   3. Por que sua sugestão é melhor do que o que já existe no código?
+   4. Realmente vale a pena demandar tempo para implementar sua ideia dentro de nossas prioridades?


Estes pontos poderiam ficar no template para abrir a issue, falei sobre isto la no template.

Acho que o template é mais um negócio pra você preencher, pra tentar dar uma estrutura previsível de como os conteúdos vão chegar até nós. Nesse sentido, o seu comentário anterior me parece muito mais um template do que estes passos... Eu espero que a pessoa, antes de preencher uma issue, já tenha realizado estes passos e use o template só como guia pra preencher a issue de forma estruturada.

williamespindola · 2018-06-10T23:40:26Z

CONTRIBUTING.md

+
+Tendo passado pelo crivo de todos estes questionamentos basta [criar uma nova issue](https://github.com/portabilis/i-educar/issues/new) descrevendo as melhorias e usando o label **melhorias**.
+
+### Pedindo recursos


Pedido de recursos e indicação de melhoria não seria a mesma coisa?

Acho que recurso seria coisa realmente nova.

Talvez os termos possam ser melhores? Realmente recurso é algo novo, que não existe no i-Educar hoje, e melhorias são ajustes ao que já existe... Alguma sugestão?

Para mim fica claro.

williamespindola · 2018-06-10T23:45:51Z

CONTRIBUTING.md

+- Seu código está completo ou próximo de estar completo;
+- Sua solução realmente funciona. Providencie testes se possível;
+- Seu código adere às convenções do [PSR-2](https://www.php-fig.org/psr/psr-2/);
+- Seus commits englobam bem as funcionalidades desenvolvidas. Evite WIPs;


Parece que estes três tópicos tem o mesmo objetivo, será que conseguirmos compilar em um único?

+- Seu código está completo ou próximo de estar completo; +- Sua solução realmente funciona. Providencie testes se possível; +- Seus commits englobam bem as funcionalidades desenvolvidas. Evite WIPs;

Se um PR foi enviado, ele tem que ser testado, mesmo o autor julgando estar pronto. A bateria de testes executada nos CIs e também execução local vai definir isto. Então quem estiver fazendo o review do PR que vai julgar se pode ser feito merge ou não.

Acho que os dois primeiros itens podem se tornar um só. O último o que eu quis dizer é que, idealmente a pessoa deve fazer os commits atômicos, como você mesmo descreveu antes @williamespindola ... A ideia é não permitir que o PR venha com um monte de commits intermediários que não englobam bem as funcionalidades que foram desenvolvidas. Vou tentar reescrever ;)

williamespindola · 2018-06-10T23:51:35Z

CONTRIBUTING.md

+#### Sobre mudanças cosméticas
+
+PRs que realizam apenas mudanças cosméticas como remoção de espaços em branco, ajustes de indentação, etc., não serão aceitos. Nós valorizamos um código bem escrito e queremos padronizar nossas práticas, mas PRs que não entregarem nenhuma melhoria na estabilidade, funcionalidade ou testabilidade do projeto serão fechados. Para entender melhor sobre esta decisão veja [esta discussão](https://github.com/rails/rails/pull/13771#issuecomment-32746700).
+


Então, mas se eu fizer um PR agora para aplicar a PSR 2 eu vou estar ajustando a indentação, então ele não será aceito?

Acho que esta muito genérico, e vale exemplificar. Fiz um comentário sobre este tipo de PR na issue 208

Acho válido se está está no planejamento. Então PSR 2 pode ser aceito sim.

Lembrar que PSR-2 é bem mais do que ajustar espaçamentos e tirar espaço em branco...

williamespindola · 2018-06-10T23:53:15Z

CONTRIBUTING.md

+- O código realmente resolve um problema real (de preferência baseado em alguma issue levantada);
+- Seu código está completo ou próximo de estar completo;
+- Sua solução realmente funciona. Providencie testes se possível;
+- Seu código adere às convenções do [PSR-2](https://www.php-fig.org/psr/psr-2/);


Devemos aplicar o PHP-FIG como um todo e não apenas a PSR-2

Acho que antes de obrigar tudo, o projeto deve ter tudo.

Etapa um seria o PSR1 e 2, então já temos que pedir isso aqui. Quando evoluirmos mais, vamos aumentando o grau de exigência. O que acha?

Vejo o FIG como um standard para todo o projeto, é certo que vamos aplicar gradualmente, mas é bom aplicar de forma global.

farribeiro · 2018-06-11T00:19:20Z

Pode fechar a #211? Fechando...

MarceloCajueiro · 2018-06-11T01:39:10Z

@williamespindola sobre os seus comentários:

Release Cycle ou Semver. Esta em definição ainda seu sei, mas não é informado aqui;

Não adianta adicionar algo que não está maduro nem escolhido.

Testes, sei que ainda não temos uma boa cobertura, mas se alguém vai contribuir precisa saber que precisa colocar, será uma condição sine qua non para seu PR ser aceito. E também nos polpa tempo no review, pois garante a funcionalidade.

Não temos nem um ambiente de teste funcional ainda. Até o projeto obrigar testes, acho que vai um tempo. A Portabilis também não vai ter condições de escrever testes nesse momento pra tudo que for fazer.

Não informa sobre documentação, se alguém adicionar uma feature nova precisa documentar isto.

Vamos abrir uma issue separada para isso, para não travar o PR.

Um pull request por feature - Se você quiser fazer mais de uma coisa, envie várias pull requests.

Faz sentido!

Se você tivesse que fazer vários commits intermediários enquanto desenvolvendo, or favor execute um squash antes de submeter. Com isto não vão precisar perguntar como fazer.

Faz sentido!

Refs #201 - Melhora e completa os templates para issues; - Adiciona esclarecimentos em alguns termnos no CONTRIBUTING.md; - Completa o CONTRIBUTING.md com mais detalhes técnicos; - Acrescenta planejamento de longo prazo (roadmap) ao README.md;

farribeiro

Quero um PR cosmético... Quebra de linhas a 80 colunas para os .md e .txt pois facilita o diff

MarceloCajueiro · 2018-06-11T02:42:13Z

.github/ISSUE_TEMPLATE/outros.md

+
+**CONTEXTO:**
+
+Porque esta alteração é importante? Como você usaria isto? Como esta alteração


"Por que" para pergunta é separado :P

Refs #201 - Limita linhas em 80 caracteres no CONTRIBUTING.md - Typo em outros.md

MarceloCajueiro · 2018-06-11T03:04:37Z

Queridos. Acho que o @eberfreitas contemplou a maioria dos ajustes pedidos. Como amanhã o i-Educar vai ser relançado, pode ser que muitas pessoas entrem no repositório, e um direcionamento é bem importante. Então vou dar merge da versão atual, mas podem continuar discutindo possíveis ajustes aqui e criando issue do que pode ser melhorado.

@williamespindola @farribeiro obrigado pelo review!

williamespindola · 2018-06-11T11:56:59Z

Go! Go! Go! \o/

farribeiro · 2018-06-11T15:30:51Z

Agora que não pode fugir do roteiro... Agora não consigo fazer um simples OT ou Anuncio

* 'master' of github.com:portabilis/i-educar: (23 commits) Corrigir link do Telegram Adicionando informações de comunicação no README Removido exclude Adicionado exclude paths EOF Create .scrutinizer Adiciona dependencias do esquema relatório que não estava presente no setup inicial do banco Corrigido ortografia Corrigido erros de ortografia Typos e ajustes; Ajustes discutidos no PR #219; Adicionando templates para issues; Versão inicial do CONTRIBUTING.md; Removido comentários Adiciona código de conduta no projeto Removido depreciado Removido script install_pear_packages.sh Removido script db.sh Apagado redundante Arquivo redundante ...

eberfreitas added 2 commits June 10, 2018 01:44

Versão inicial do CONTRIBUTING.md;

28e870d

Refs #201 - Adiciona o arquivo CONTRIBUTING.md; - Revisiona o README.md apontando para o guia e outros ajustes.

Adicionando templates para issues;

bef1603

Refs #201 Permite a utilização de templates para a criação de bug reports e outros assuntos com integração à interface do GitHub.

eberfreitas mentioned this pull request Jun 10, 2018

Contributing #201

Closed

MarceloCajueiro approved these changes Jun 10, 2018

View reviewed changes

williamespindola suggested changes Jun 11, 2018

View reviewed changes

williamespindola mentioned this pull request Jun 11, 2018

Contributing #211

Closed

MarceloCajueiro mentioned this pull request Jun 11, 2018

Documentar como deve-se trabalhar com documentação do projeto #221

Closed

Ajustes discutidos no PR #219;

6fb6f45

Refs #201 - Melhora e completa os templates para issues; - Adiciona esclarecimentos em alguns termnos no CONTRIBUTING.md; - Completa o CONTRIBUTING.md com mais detalhes técnicos; - Acrescenta planejamento de longo prazo (roadmap) ao README.md;

farribeiro reviewed Jun 11, 2018

View reviewed changes

MarceloCajueiro reviewed Jun 11, 2018

View reviewed changes

Typos e ajustes;

204f749

Refs #201 - Limita linhas em 80 caracteres no CONTRIBUTING.md - Typo em outros.md

MarceloCajueiro merged commit 98f29a6 into portabilis:master Jun 11, 2018


		Outra ótima forma de contribuir é indicando melhorias ao código do i-Educar e em como ele está estruturado. Se você tem qualquer ideia de como podemos melhorar alguma abordagem na solução de problemas, refatoração de código, melhoria em algum recurso ou qualquer outra coisa relacionada, siga estes passos:

		1. Certifique-se de que sua ideia já não esteja sendo abordada em nosso [roadmap](./README.md#roadmap-de-tecnologia);


		Tendo passado pelo crivo de todos estes questionamentos basta [criar uma nova issue](https://github.com/portabilis/i-educar/issues/new) descrevendo as melhorias e usando o label melhorias.

		### Pedindo recursos

		#### Sobre mudanças cosméticas

		PRs que realizam apenas mudanças cosméticas como remoção de espaços em branco, ajustes de indentação, etc., não serão aceitos. Nós valorizamos um código bem escrito e queremos padronizar nossas práticas, mas PRs que não entregarem nenhuma melhoria na estabilidade, funcionalidade ou testabilidade do projeto serão fechados. Para entender melhor sobre esta decisão veja [esta discussão](https://github.com/rails/rails/pull/13771#issuecomment-32746700).


		CONTEXTO:

		Porque esta alteração é importante? Como você usaria isto? Como esta alteração

Guia de contribuição #219

Guia de contribuição #219

Conversation

eberfreitas commented Jun 10, 2018

farribeiro commented Jun 10, 2018

MarceloCajueiro left a comment

Choose a reason for hiding this comment

MarceloCajueiro commented Jun 10, 2018

williamespindola commented Jun 10, 2018

williamespindola left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Contexto

Possível implementação

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

farribeiro commented Jun 11, 2018 • edited Loading

MarceloCajueiro commented Jun 11, 2018

farribeiro left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MarceloCajueiro commented Jun 11, 2018

williamespindola commented Jun 11, 2018

farribeiro commented Jun 11, 2018 • edited Loading

farribeiro commented Jun 11, 2018 •

edited

Loading

farribeiro commented Jun 11, 2018 •

edited

Loading