Guia de contribuição

.github/ISSUE_TEMPLATE/bugs.md

@@ -0,0 +1,26 @@
+---
+name: "Reportar um bug"
+about: Encontrou um bug no i-Educar? Use este template!
+---
+
+Olá e obrigado por nos ajudar a tornar o i-Educar um projeto mais estável. Para
+reportar seu bug use o template abaixo:
+
+**MENU:**
+
+Nesta seção deve ser apontado qual o menu no sistema deve ser realizada a alteração.
+
+**DESCRIÇÃO:**
+
+Nesta seção deve ser colocado uma descrição do problema ou necessidade.
+
+**OBSERVAÇÕES:**
+
+Observações em geral sobre o problema apontado.
+
+**AMBIENTE:**
+
+- Plataforma utilizada (p.ex. Docker, instalação direta):
+- Sistema operacional e versão (p.ex. Ubuntu 16.04, Windows 7):
+- Navegador e versão (p.ex. Chrome 35.9.9.9):
+- Outros detalhes importantes:

.github/ISSUE_TEMPLATE/outros.md

@@ -0,0 +1,19 @@
+---
+name: "Outros"
+about: Para indicar melhorias ou recursos use este template!
+---
+
+Olá e obrigado por nos ajudar a tornar o i-Educar um projeto melhor. Não esqueça
+de revisar o nosso
+[guia de contribuição](https://github.com/portabilis/i-educar/blob/master/CONTRIBUTING.md)
+para saber melhor como colaborar com a nossa comunidade. Você também pode usar
+o template abaixo para preencher sua issue:
+
+**CONTEXTO:**
+
+Por que esta alteração é importante? Como você usaria isto? Como esta alteração
+pode beneficiar outros usuários?
+
+**IMPLEMENTAÇÃO:**
+
+Não obrigatório, mas sugira uma idéia de como isto poderia ser implementado.

CONTRIBUTING.md

@@ -0,0 +1,214 @@
+# Guia de contribuição
+
+Que bom que você resolveu contribuir conosco. Obrigado! A proposta do i-Educar é
+ambiciosa e precisamos de toda ajuda possível para alcançar nossos objetivos.
+Neste guia vamos explicar como funcionam os nossos processos internos e como
+podemos trabalhar juntos da melhor forma possível.
+
+## Como contribuir
+
+Existem diversas formas de contribuir com o projeto:
+
+- [Reportando bugs](#reportando-bugs)
+- [Indicando melhorias](#indicando-melhorias)
+- [Pedindo recursos](#pedindo-recursos)
+- [Discutindo as issues](#discutindo-as-issues)
+- [Fazendo pull requests](#fazendo-pull-requests)
+- [Outras formas de contribuir](#outras-formas-de-contribuir)
+
+### Reportando bugs
+
+Se encontrou um bug no i-Educar você pode reportá-lo usando a ferramenta de
+[issues do GitHub](https://github.com/portabilis/i-educar/issues). Porém antes
+de enviar seu bug é importante fazer as seguintes verificações:
+
+1. Atualize seu repositório local no branch `master` mais recente. Talvez seu
+   bug já tenha sido corrigido na versão mais recente;
+2. Verifique se o bug já foi reportado por outra pessoa fazendo uma busca pelas
+   issues.
+
+Se o bug realmente não foi resolvido ou acolhido então está na hora de
+[criar uma nova issue](https://github.com/portabilis/i-educar/issues/new). No
+título da issue tente resumir da melhor forma o problema evitando títulos
+genéricos como *"Falha no sistema"* ou *"Problemas na instalação"*. No corpo da
+issue, tente seguir o seguinte formato:
+
+```
+**MENU:** Nesta seção deve ser apontado qual o menu no sistema deve ser
+realizada a alteração.
+
+**DESCRIÇÃO:** Nesta seção deve ser colocado uma descrição do problema ou
+necessidade.
+
+**OBSERVAÇÕES:** Observações em geral sobre o problema apontado.
+```
+
+Exemplo:
+
+```
+**MENU:**
+
+i-Educar - Escola > Cadastro > Turma > Cadastrar
+
+**DESCRIÇÃO:**
+
+No cadastro de turmas, ao selecionar a opção Multi-seriada, todas as séries
+aparecem para seleção, quando deveria ser somente as da escola e curso
+selecionado.
+
+**OBSERVAÇÕES:**
+
+Não se aplica.
+
+```
+
+Se possível inclua imagens ou vídeos à descrição do bug para facilitar o
+processo de reprodução. Use um software como
+[LICEcap](https://www.cockos.com/licecap/) para criar um gif animado de sua
+tela. Informe também detalhes sobre o seu ambiente: plataforma de execução,
+sistema operacional, navegador e versão, etc. Você também deve adicionar o
+label **bug** à issue.
+
+#### Nota sobre falhas de segurança
+
+Se você encontrou alguma falha de segurança **não use as issues para reportar o
+bug**. Escreva o seu report diretamente para o endereço de e-mail
+`comunidade@portabilis.com.br`. Ele será analisado, validado e corrigido de
+acordo com as necessidades. Pedimos que **não torne a falha pública** para
+segurança de todos que utilizam a plataforma em seu estado atual.
+
+### Indicando melhorias
+
+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);
+2. Também verifique se a ideia já não está pressente em nossas
+   [issues do GitHub](https://github.com/portabilis/i-educar/issues);
+3. Defenda a sua ideia e explique de forma convincente porque ela deve ser
+   acolhida. Eis algumas questões a considerar:
+   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?
+
+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
+
+Tendo em vista o que estamos construindo junto com a comunidade, novos recursos
+tem baixa prioridade no nosso fluxo. Vale a pena enviar sua sugestão de recurso
+apenas se:
+
+1. O recurso em questão resolve um problema que não é resolvido por nada que já
+   exista no projeto;
+2. O recurso resolve um problema real validado por pessoas que estão em contato
+   direto com a utilização da plataforma: secretários, gestores, professores,
+   alunos, etc.
+
+Um exemplo de um bom recurso implementado para o i-Educar é o módulo do **censo
+escolar** que visa resolver todo o processo de exportação de dados para o censo
+escolar com apenas alguns cliques, otimizando de forma radical este processo que
+antes poderia demorar semanas envolvendo o trabalho de muitas pessoas.
+
+Para criar seu pedido de recurso basta
+[criar uma nova issue](https://github.com/portabilis/i-educar/issues/new) usando
+o label **recurso**.
+
+### Discutindo as issues
+
+Antes de partirmos para o código em si é muito importante discutirmos com a
+comunidade como cada issue será abordada. Toda e qualquer questão deve ser
+colocada em discussão para que qualquer pessoa que deseje solucionar aquele
+problema tenha o máximo de informações para executar uma solução.
+
+Idealmente todas as issues devem ter um plano de ação claro antes que qualquer
+código seja escrito. Sabemos que muitas vezes isto não é possível, sendo
+necessário explorar e analisar melhor o que foi indicado. Nestes casos, publique
+todas as suas descobertas nas discussões indicando caminhos e recebendo o
+feedback da comunidade a respeito do que está sendo proposto.
+
+Issues que estão em processo de discussão devem receber o label **discussão**
+indicando que aquela issue precisa dos inputs e feedbacks dos membros da
+comunidade. Nós te encorajamos a participar o máximo possível mas fique atento
+ao nosso [código de conduta](./CODE_OF_CONDUCT.md) antes de realizar qualquer
+interação com os outros membros da comunidade.
+
+### Fazendo pull requests
+
+Depois de ter um plano de ação relativamente claro você deve estar pronto para
+contribuir com código. Para isso faça um fork do i-Educar e trabalhe em cima de
+um branch diferente de master implementando suas soluções. Para saber mais sobre
+pull requests e como eles funcionam, veja
+[este link](https://help.github.com/articles/about-pull-requests/).
+
+Antes de abrir seu PR (pull request) certique-se que:
+
+- O código realmente resolve um problema real (de preferência baseado em alguma
+  issue levantada);
+- Seu PR resolve uma issue apenas. Se você quiser fazer mais de uma coisa,
+  divida em vários PRs;
+- Seu código é funcional (ou algo próximo disso). 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 espalhar o
+  desenvolvimento de um recurso em múltiplos commits;
+- Se for inevitável criar vários commits intermediários, por favor execute um
+  [squash](https://git-scm.com/book/pt-br/v1/Ferramentas-do-Git-Reescrevendo-o-Hist%C3%B3rico#Achatando-um-Commit)
+  antes de abrir seu PR;
+- As mensagens de seus commits são claras e descrevem bem o trabalho. Para
+  maiores dicas sobre como escrever mensagens de commit adequadas, veja
+  [este guia](https://chris.beams.io/posts/git-commit/).
+
+Caso seu PR não atenda a uma destas demandas ele poderá ser fechado. Isto inclui
+PRs que tentam resolver problemas reais mas que contém código cheio de erros ou
+soluções incompletas. Para que a nossa lista de PRs não fique poluída,
+dificultando o trabalho de outros membros da comunidade que podem ajudar
+revisando as mudanças, pedimos que PRs sejam abertos quando sua solução estiver
+a mais completa possível. Por isso é imprescindível usar a discussão nas issues
+para a criação de soluções mais acertivas.
+
+#### 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, testabilidade do projeto ou
+compatibilidade com os padrões sendo adotados (PSR-2) serão fechados. Para
+entender melhor sobre esta decisão veja
+[esta discussão](https://github.com/rails/rails/pull/13771#issuecomment-32746700).
+
+### Outras formas de contribuir
+
+Se você não trabalha com código mas quer ajudar o i-Educar, existe muitas outras
+formas de contribuir:
+
+- Ajude com a documentação do projeto (mais informações em breve);
+- Fale sobre o i-Educar nas suas redes sociais, blogs, etc. Espalhe a palavra;
+- Organize eventos e dê palestras sobre o i-Educar;
+- Crie material promocional como apresentações, screencasts, mídia para
+  compartilhamento em redes sociais, etc;
+- Viu alguma discussão que te interessa e onde você pode acrescentar mesmo sem
+  conhecimento técnico? Não se acanhe e participe também nas issues do GitHub.
+
+Pensou em alguma outra forma de contribuir? Compartilha com a gente! Escreva
+para `comunidade@portabilis.com.br` e conte sua história.
+
+# Créditos
+
+Este documento foi escrito com o auxílio de outros documentos similares
+utilizados em outras comunidades. Destacamos:
+
+- [Metabase](https://github.com/metabase/metabase/blob/master/docs/contributing.md)
+- [Ghost](https://docs.ghost.org/v1/docs/contributing)
+- [Ember.js](https://github.com/emberjs/ember.js/blob/master/CONTRIBUTING.md)
+- [Ruby on Rails](https://github.com/rails/rails/blob/master/CONTRIBUTING.md)
+- [Propostas de William Espindola](https://github.com/portabilis/i-educar/issues/201)
+
+... dentre outros!

README.md

@@ -5,52 +5,53 @@ _“Lançando o maior software livre educacional do Brasil!”._
 **Nós somos a Comunidade i-Educar e acreditamos que podemos transformar o nosso
 país por meio da educação. Junte-se a nós!**
 
-O i-Educar é um software livre e público totalmente on-line que torna mais fácil
-e prática a gestão dos processos das escolas, matrículas e dados de alunos,
-apoiando os profissionais da rede de ensino e gestores a resolverem os desafios
-da educação dentro e fora da sala de aula.
-
 ## Conteúdo
 
-1. [Cenário atual](#cenário-atual)
-2. [Sobre o i-Educar](#sobre-o-i-educar)
-3. [Instalação](#instalação)
-4. [Solicite demonstração do software](#solicite-demonstração-do-software)
-5. [Solicite prestação de serviço](#solicite-prestação-de-serviço)
-
-## Cenário atual
-
-No final de 2017, a Portabilis, organização que é integrante da comunidade desde
-2009 e tem o papel de mantenedora do projeto, propôs uma renovação de energias
-para levar o i-Educar ainda mais longe. (Leia aqui o manifesto:
-[i-Educar por todo o Brasil](https://softwarepublico.gov.br/social/i-educar/blog/em-2018-queremos-o-i-educar-por-todo-o-brasil)).
-
-No sentido desta iniciativa, está a proposta de acabar com a defasagem da versão
-aberta e aumentar a aproximação com os seus usuários. No dia 31 de janeiro, a
-Portabilis anunciou o apoio da Fundação Lemann para potencializar todos esses
-objetivos (Saiba mais aqui:
-[Preparação do lançamento do maior software livre educacional do Brasil!](https://medium.com/portabilis/prepara%C3%A7%C3%A3o-do-lan%C3%A7amento-do-maior-software-educacional-open-source-do-brasil-305e57143372)).
-
-### Etapas iniciais deste processo
-
-1. Liberar na versão Comunidade as principais melhorias feitas pela Portabilis
-   nos últimos anos;
-2. A Portabilis irá mudar seu fluxo de trabalho passando a desenvolver
-   diretamente no repositório da Comunidade;
-3. Planejar tecnicamente o projeto, com foco em refatoração e criação de
-   padrões, para possibilitar o crescimento e expansão do uso do i-Educar;
-4. Iniciar as refatorações propostas na fase de planejamento permitindo
-   contribuições de forma mais ativa;
-5. Evoluir constantemente o i-Educar com ênfase nos usuários e na facilidade do
-   uso em redes públicas de ensino.
-
-## Sobre o i-Educar
-
-O i-Educar é um software livre e público para a gestão escolar que foi
-desenvolvido originalmente pela Prefeitura de Itajaí-SC e disponibilizado como
-Software Livre no Portal do Software Público Brasileiro
-(https://softwarepublico.gov.br), onde atualmente é mantido pela Comunidade
-i-Educar.
+1. [Sobre o i-Educar](#sobre-o-i-educar)
+2. [Roadmap de tecnologia](#roadmap-de-tecnologia)
+3. [Como contribuir](#como-contribuir)
+4. [Instalação](#instalação)
+
+## Sobre i-Educar
+
+O i-Educar é um software livre de gestão escolar totalmente on-line que permite
+secretários escolares, professores, coordenadores e gestores da área possam
+utilizar uma ferramenta que produz informações e estatísticas em tempo real,
+com um banco de dados centralizado e de fácil acesso, diminuindo a necessidade
+de uso de papel, a duplicidade de documentos, o tempo de atendimento ao cidadão
+e racionalizando o trabalho do servidor público.
+
+Ele foi originalmente desenvolvido pela prefeitura de Itajaí - SC e
+disponibilizado no Portal do Software Público do Governo Federal em 2008, com o
+objetivo de atender às necessidades das Secretarias de Educação e Escolas
+Públicas de **todo o Brasil**.
+
+## Roadmap de tecnologia
+
+O i-Educar por ser um sistema antigo e por não ter seguido um padrão específico,
+precisa passar por um processo de melhoria para diminuir a quantidade de bugs,
+melhorar a manutenibilidade e enfim permitir a evolução através de features.
+
+### Passos iniciais
+
+- Adoção do [PSR1](https://www.php-fig.org/psr/psr-1/)
+- Adoção do [PSR2](https://www.php-fig.org/psr/psr-2/)
+- Adoção do [PSR4](https://www.php-fig.org/psr/psr-4/)
+- Iniciar a cobertura de testes para possibilitar refatorações
+
+### Planejamento Técnico
+
+Em nossa wiki você encontra um planejamento mais técnico de como devemos
+prosseguir com as melhorias e evoluções do nosso projeto.
+[Clique aqui](https://github.com/portabilis/i-educar/wiki/Planejamento-T%C3%A9cnico)
+para ler mais a respeito.
+
+## Como contribuir
+
+Contribuições são **super bem vindas**! Se você tem vontade de construir o
+i-Educar junto conosco, veja o nosso [guia de contribuição](./CONTRIBUTING.md)
+onde explicamos detalhadamente como trabalhamos e de que formas você pode nos
+ajudar a alcançar nossos objetivos.
 
 ## Instalação
 
@@ -87,6 +88,9 @@ clonado em sua máquina:
 $ git clone https://github.com/portabilis/i-educar-reports-package.git ieducar/modules/Reports
 ```
 
+P.S.: Esses relatórios são legados e podem não funcionar. Em breve vamos lançar
+um pacote de mais de 40 relatórios funcionais.
+
 ### Instalando outras dependências
 
 O i-Educar usa o [Composer](https://getcomposer.org/) para gerenciar suas
@@ -146,19 +150,9 @@ realizar seu primeiro acesso ao i-Educar. Basta acessar o seguinte endereço:
 
 O usuário padrão é: `admin` / A senha padrão é: `123456789`
 
-Assim que realizar seu primeiro acesso **não se esqueça de alterar a senha padrão**.
-
-## Solicite demonstração do software
-
-Para solicitar uma demonstração, nos envie uma mensagem ou nos ligue por meio da
-nossa [página de contato](http://goo.gl/O0JBs).
-
-## Solicite prestação de serviço
-
-Para solicitar serviço de migração de dados, instalação, atualização, correções
-ou desenvolvimento de alterações, entre em contato por meio da nossa
-[página de contato](http://goo.gl/O0JBs).
+Assim que realizar seu primeiro acesso **não se esqueça de alterar a senha
+padrão**.
 
 ---
 
-[Portabilis Tecnologia](http://www.portabilis.com.br/)
+Powered by [Portabilis Tecnologia](http://www.portabilis.com.br/)