Download as
Browse Code »

Commit 28e870df5963106a46ad64d295d0d5cfa855102a

Authored by Éber Freitas Dias
1 parent a4e4e2a5
Exists in 2.8 and in 8 other branches 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7

Versão inicial do CONTRIBUTING.md; 

Refs portabilis/i-educar#201

- Adiciona o arquivo CONTRIBUTING.md;
- Revisiona o README.md apontando para o guia e outros ajustes.
Showing 2 changed files with 174 additions and 57 deletions   Show diff stats
CONTRIBUTING.md 0 → 100644
  Diff comments   View file @28e870d
... ... @@ -0,0 +1,130 @@
  1 +# Guia de contribuição
  2 +
  3 +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.
  4 +
  5 +## Como contribuir
  6 +
  7 +Existem diversas formas de contribuir com o projeto:
  8 +
  9 +- [Reportando bugs](#reportando-bugs)
  10 +- [Indicando melhorias](#indicando-melhorias)
  11 +- [Pedindo recursos](#pedindo-recursos)
  12 +- [Discutindo as issues](#discutindo-as-issues)
  13 +- [Fazendo pull requests](#fazendo-pull-requests)
  14 +- [Outras formas de contribuir](#outras-formas-de-contribuir)
  15 +
  16 +### Reportando bugs
  17 +
  18 +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:
  19 +
  20 +1. Atualize seu repositório local no branch `master` mais recente. Talvez seu bug já tenha sido corrigido na versão mais recente;
  21 +2. Verifique se o bug já foi reportado por outra pessoa fazendo uma busca pelas issues.
  22 +
  23 +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:
  24 +
  25 +```
  26 +**MENU:** Nesta seção deve ser apontado qual o menu no sistema deve ser realizada a alteração.
  27 +
  28 +**DESCRIÇÃO:** Nesta seção deve ser colocado uma descrição do problema ou necessidade.
  29 +
  30 +**OBSERVAÇÕES:** Observações em geral sobre o problema apontado.
  31 +```
  32 +
  33 +Exemplo:
  34 +
  35 +```
  36 +**MENU:**
  37 +
  38 +i-Educar - Escola > Cadastro > Turma > Cadastrar
  39 +
  40 +**DESCRIÇÃO:**
  41 +
  42 +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.
  43 +
  44 +**OBSERVAÇÕES:**
  45 +
  46 +Não se aplica.
  47 +
  48 +```
  49 +
  50 +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. Você também deve adicionar o label **bug** à issue.
  51 +
  52 +#### Nota sobre falhas de segurança
  53 +
  54 +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.
  55 +
  56 +### Indicando melhorias
  57 +
  58 +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:
  59 +
  60 +1. Certifique-se de que sua ideia já não esteja sendo abordada em nosso [roadmap](./README.md#roadmap-de-tecnologia);
  61 +2. Também verifique se a ideia já não está pressente em nossas [issues do GitHub](https://github.com/portabilis/i-educar/issues);
  62 +3. Defenda a sua ideia e explique de forma convincente porque ela deve ser acolhida. Eis algumas questões a considerar:
  63 + 1. Você realmente esta propondo uma ideia só ou um conjunto de ideias?
  64 + 2. Qual é o problema que sua ideia resolve?
  65 + 3. Por que sua sugestão é melhor do que o que já existe no código?
  66 + 4. Realmente vale a pena demandar tempo para implementar sua ideia dentro de nossas prioridades?
  67 +
  68 +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**.
  69 +
  70 +### Pedindo recursos
  71 +
  72 +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:
  73 +
  74 +1. O recurso em questão resolve um problema que não é resolvido por nada que já exista no projeto;
  75 +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.
  76 +
  77 +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.
  78 +
  79 +Para criar seu pedido de recurso basta [criar uma nova issue](https://github.com/portabilis/i-educar/issues/new) usando o label **recurso**.
  80 +
  81 +### Discutindo as issues
  82 +
  83 +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.
  84 +
  85 +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.
  86 +
  87 +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.
  88 +
  89 +### Fazendo pull requests
  90 +
  91 +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/).
  92 +
  93 +Antes de abrir seu PR (pull request) certique-se que:
  94 +
  95 +- O código realmente resolve um problema real (de preferência baseado em alguma issue levantada);
  96 +- Seu código está completo ou próximo de estar completo;
  97 +- Sua solução realmente funciona. Providencie testes se possível;
  98 +- Seu código adere às convenções do [PSR-2](https://www.php-fig.org/psr/psr-2/);
  99 +- Seus commits englobam bem as funcionalidades desenvolvidas. Evite WIPs;
  100 +- 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/).
  101 +
  102 +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.
  103 +
  104 +#### Sobre mudanças cosméticas
  105 +
  106 +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).
  107 +
  108 +### Outras formas de contribuir
  109 +
  110 +Se você não trabalha com código mas quer ajudar o i-Educar, existe muitas outras formas de contribuir:
  111 +
  112 +- Ajude com a documentação do projeto (mais informações em breve);
  113 +- Fale sobre o i-Educar nas suas redes sociais, blogs, etc. Espalhe a palavra;
  114 +- Organize eventos e dê palestras sobre o i-Educar;
  115 +- Crie material promocional como apresentações, screencasts, mídia para compartilhamento em redes sociais, etc;
  116 +- 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.
  117 +
  118 +Pensou em alguma outra forma de contribuir? Compartilha com a gente! Escreva para `comunidade@portabilis.com.br` e conte sua história.
  119 +
  120 +# Créditos
  121 +
  122 +Este documento foi escrito com o auxílio de outros documentos similares utilizados em outras comunidades. Destacamos:
  123 +
  124 +- [Metabase](https://github.com/metabase/metabase/blob/master/docs/contributing.md)
  125 +- [Ghost](https://docs.ghost.org/v1/docs/contributing)
  126 +- [Ember.js](https://github.com/emberjs/ember.js/blob/master/CONTRIBUTING.md)
  127 +- [Ruby on Rails](https://github.com/rails/rails/blob/master/CONTRIBUTING.md)
  128 +- [Propostas de William Espindola](https://github.com/portabilis/i-educar/issues/201)
  129 +
  130 +... dentre outros!
... ...
README.md
  Diff comments   View file @28e870d
... ... @@ -5,52 +5,46 @@ _“Lançando o maior software livre educacional do Brasil!”._
5 5 **Nós somos a Comunidade i-Educar e acreditamos que podemos transformar o nosso
6 6 país por meio da educação. Junte-se a nós!**
7 7  
8   -O i-Educar é um software livre e público totalmente on-line que torna mais fácil
9   -e prática a gestão dos processos das escolas, matrículas e dados de alunos,
10   -apoiando os profissionais da rede de ensino e gestores a resolverem os desafios
11   -da educação dentro e fora da sala de aula.
12   -
13 8 ## Conteúdo
14 9  
15   -1. [Cenário atual](#cenário-atual)
16   -2. [Sobre o i-Educar](#sobre-o-i-educar)
17   -3. [Instalação](#instalação)
18   -4. [Solicite demonstração do software](#solicite-demonstração-do-software)
19   -5. [Solicite prestação de serviço](#solicite-prestação-de-serviço)
20   -
21   -## Cenário atual
22   -
23   -No final de 2017, a Portabilis, organização que é integrante da comunidade desde
24   -2009 e tem o papel de mantenedora do projeto, propôs uma renovação de energias
25   -para levar o i-Educar ainda mais longe. (Leia aqui o manifesto:
26   -[i-Educar por todo o Brasil](https://softwarepublico.gov.br/social/i-educar/blog/em-2018-queremos-o-i-educar-por-todo-o-brasil)).
27   -
28   -No sentido desta iniciativa, está a proposta de acabar com a defasagem da versão
29   -aberta e aumentar a aproximação com os seus usuários. No dia 31 de janeiro, a
30   -Portabilis anunciou o apoio da Fundação Lemann para potencializar todos esses
31   -objetivos (Saiba mais aqui:
32   -[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)).
33   -
34   -### Etapas iniciais deste processo
35   -
36   -1. Liberar na versão Comunidade as principais melhorias feitas pela Portabilis
37   - nos últimos anos;
38   -2. A Portabilis irá mudar seu fluxo de trabalho passando a desenvolver
39   - diretamente no repositório da Comunidade;
40   -3. Planejar tecnicamente o projeto, com foco em refatoração e criação de
41   - padrões, para possibilitar o crescimento e expansão do uso do i-Educar;
42   -4. Iniciar as refatorações propostas na fase de planejamento permitindo
43   - contribuições de forma mais ativa;
44   -5. Evoluir constantemente o i-Educar com ênfase nos usuários e na facilidade do
45   - uso em redes públicas de ensino.
46   -
47   -## Sobre o i-Educar
48   -
49   -O i-Educar é um software livre e público para a gestão escolar que foi
50   -desenvolvido originalmente pela Prefeitura de Itajaí-SC e disponibilizado como
51   -Software Livre no Portal do Software Público Brasileiro
52   -(https://softwarepublico.gov.br), onde atualmente é mantido pela Comunidade
53   -i-Educar.
  10 +1. [Sobre o i-Educar](#sobre-o-i-educar)
  11 +2. [Roadmap de tecnologia](#roadmap-de-tecnologia)
  12 +3. [Como contribuir](#como-contribuir)
  13 +4. [Instalação](#instalação)
  14 +
  15 +## Sobre i-Educar
  16 +
  17 +O i-Educar é um software livre de gestão escolar totalmente on-line que permite
  18 +secretários escolares, professores, coordenadores e gestores da área possam
  19 +utilizar uma ferramenta que produz informações e estatísticas em tempo real,
  20 +com um banco de dados centralizado e de fácil acesso, diminuindo a necessidade
  21 +de uso de papel, a duplicidade de documentos, o tempo de atendimento ao cidadão
  22 +e racionalizando o trabalho do servidor público.
  23 +
  24 +Ele foi originalmente desenvolvido pela prefeitura de Itajaí - SC e
  25 +disponibilizado no Portal do Software Público do Governo Federal em 2008, com o
  26 +objetivo de atender às necessidades das Secretarias de Educação e Escolas
  27 +Públicas de **todo o Brasil**.
  28 +
  29 +## Roadmap de tecnologia
  30 +
  31 +O i-Educar por ser um sistema antigo e por não ter seguido um padrão específico,
  32 +precisa passar por um processo de melhoria para diminuir a quantidade de bugs,
  33 +melhorar a manutenibilidade e enfim permitir a evolução através de features.
  34 +
  35 +### Passos iniciais
  36 +
  37 +- Adoção do [PSR1](https://www.php-fig.org/psr/psr-1/)
  38 +- Adoção do [PSR2](https://www.php-fig.org/psr/psr-2/)
  39 +- Adoção do [PSR4](https://www.php-fig.org/psr/psr-4/)
  40 +- Iniciar a cobertura de testes para possibilitar refatorações
  41 +
  42 +## Como contribuir
  43 +
  44 +Contribuições são **super bem vindas**! Se você tem vontade de construir o
  45 +i-Educar junto conosco, veja o nosso [guia de contribuição](./CONTRIBUTING.md)
  46 +onde explicamos detalhadamente como trabalhamos e de que formas você pode nos
  47 +ajudar a alcançar nossos objetivos.
54 48  
55 49 ## Instalação
56 50  
... ... @@ -87,6 +81,9 @@ clonado em sua máquina:
87 81 $ git clone https://github.com/portabilis/i-educar-reports-package.git ieducar/modules/Reports
88 82 ```
89 83  
  84 +P.S.: Esses relatórios são legados e podem não funcionar. Em breve vamos lançar
  85 +um pacote de mais de 40 relatórios funcionais.
  86 +
90 87 ### Instalando outras dependências
91 88  
92 89 O i-Educar usa o [Composer](https://getcomposer.org/) para gerenciar suas
... ... @@ -146,19 +143,9 @@ realizar seu primeiro acesso ao i-Educar. Basta acessar o seguinte endereço:
146 143  
147 144 O usuário padrão é: `admin` / A senha padrão é: `123456789`
148 145  
149   -Assim que realizar seu primeiro acesso **não se esqueça de alterar a senha padrão**.
150   -
151   -## Solicite demonstração do software
152   -
153   -Para solicitar uma demonstração, nos envie uma mensagem ou nos ligue por meio da
154   -nossa [página de contato](http://goo.gl/O0JBs).
155   -
156   -## Solicite prestação de serviço
157   -
158   -Para solicitar serviço de migração de dados, instalação, atualização, correções
159   -ou desenvolvimento de alterações, entre em contato por meio da nossa
160   -[página de contato](http://goo.gl/O0JBs).
  146 +Assim que realizar seu primeiro acesso **não se esqueça de alterar a senha
  147 +padrão**.
161 148  
162 149 ---
163 150  
164   -[Portabilis Tecnologia](http://www.portabilis.com.br/)
  151 +Powered by [Portabilis Tecnologia](http://www.portabilis.com.br/)
... ...