Como contribuir
Índice
- Relatar um bug
- Criar um patch
- Criar uma nova funcionalidade
- Pedir ajuda no fórum de suporte
- Ajudar pessoas com dificuldades no fórum de suporte
- Transformar as dúvidas mais frequentes do fórum de suporte em itens do FAQ
- Contribuir com a documentação
- Organize eventos, dê palestras
- Criar material promocional
- Escrever posts no seu blog sobre o i-Educar
- Discutir como o i-Educar pode ser melhorado no fórum de desenvolvimento e …
- Créditos
No Software Livre, existem diversas formas para contribuir com a melhoria de um software. Você não precisa ser um hacker de PHP nem de PostgreSQL para contribuir com o i-Educar (mas se for, ficamos muito agradecidos!). Algumas formas de contribuir são:
Relatar um bug
Relatar um bug ajuda os desenvolvedores do i-Educar a corrigir de forma mais rápida um comportamento não desejado. Nós usamos o sistema de tickets do Trac do i-Educar para coordenar a correção de bugs. Antes de abrir um ticket, pedimos que faça alguns passos antes de relatar o bug:
- Verifique se o bug já não foi relatado com um ticket:
- Não crie um ticket caso já exista um para o bug (mesmo que a descrição seja um pouco diferente). Caso queira acrescentar alguma informação sobre o bug que possa ser útil, crie um comentário no ticket já existente;
- Verifique nos fóruns da comunidade se existe algo parecido. Pode ser que você tenha esquecido algum passo na instalação ou na configuração;
- Nunca use o sistema de tickets para solicitar suporte. Use o fórum Suporte para esse propósito.
Ao fazer os passos acima e não encontrar nada semelhante ao que achou, você pode ter se deparado com um bug. Preencha o formulário de novo ticket e siga as seguintes orientações:
- Use o campo Breve resumo para descrever o objetivo do seu ticket;
- Selecione o tipo de ticket apropriado (defect para bug, enhancement para pedidos de melhorias/funcionalidades e task para tarefas de projeto);
- Seja o mais descritivo possível: informe o seu sistema operacional, a versão do PHP e do PostgreSQL que estão instalados e das bibliotecas auxiliares;
- Descreva o contexto ao qual o bug fora identificado: os passos para reproduzir o erro (página inicial, páginas intermediárias e página do erro e o que foi digitado, quando bug ocorrer em um formulário);
- Informe o navegador (e a versão) e anexe um printscreen da página com erro caso seja de layout;
- Caso já tenha criado um patch, anexe-o no ticket e prefixe o Breve resumo com [PATCH]:
[PATCH] Cadastro de aluno não grava data de criação corretamente
Relatar uma falha de segurança
Falhas de segurança serão tratadas de forma diferente de outros bugs. Caso encontre uma falha de segurança, por favor, envie um e-mail para seg.ieducar [arroba] gmail [ponto] com. Este e-mail encaminha para todos os desenvolvedores com acesso ao repositório.
Sua falha será analisada e você terá uma resposta sobre como o problema será corrigido e qual a previsão da liberação da correção. Enquanto isso, pedimos que não torne a falha pública.
Criar um patch
Para contribuir com um patch, que pode ser para correção de um bug ou melhoria de um trecho de código, certifique-se que seu código está em conformidade com os padrões de codificação.
Para criar um patch, você precisa ter uma cópia de trabalho do repositório SVN do i-Educar. Então, após fazer suas modificações, execute o comando svn diff:
$ cd /var/www/ieducar-svn $ svn diff arquivo-alterado.php > /tmp/patch-arquivo-alterado.diff $ svn diff > /tmp/patch-descricao.diff
Onde:
- A primeira forma é para ser usada quando apenas um arquivo foi alterado;
- Na segunda forma, mais de um arquivo foi alterado;
- Use a extensão .diff para o arquivo de patch e nomeie-o como desejar (seja sucinto).
Anexe o patch a um ticket existente ou ao ticket em que estiver abrindo e prefixe o Breve resumo do ticket com [PATCH].
Para aplicar o patch na sua base de código para testá-lo, utilize o utilitário patch:
$ cd /var/www/ieducar-svn $ patch -p0 < /tmp/patch-descricao.diff
Importante: teste a sua alteração, verificando se não quebrou nenhuma outra parte relacionada antes de contribuir o patch. Sempre devemos fazer o commit apenas de código funcional, para evitar quebrar o ambiente de trabalho de algum outro desenvolvedor ou de adicionar bugs obscuros no software. Ferramentas de integração contínua e de TDD poderão ser adotadas pela comunidade para garantir essa qualidade no código.
Criar uma nova funcionalidade
Se você alterou o código fonte do i-Educar para criar uma nova funcionalidade ou irá criar uma para alguma necessidade específica, contribua com o projeto disponibilizando-a em nosso repositório.
Caso encontre algum ticket com pedido de nova funcionalidade que julga ser interessante desenvolver e esteja disposto a fazê-lo, pegue o ticket para si (colocando o seu nome/e-mail no campo Assign to do ticket).
Permissão de commit no repositório
Para poder fazer commits no repositório SVN do i-Educar e contribuir com novas funcionalidades, melhorias e correções diretamente, peça permissão de acesso através do e-mail: admin @ softwarepublico.gov.br com o assunto Permissão commit SVN i-Educar. Seu pedido será rapidamente analisado (podemos fazer algumas perguntas antes somente para saber se realmente está comprometido em ajudar a manter nossa organização) e terá uma resposta o mais breve possível.
Importante: teste a sua alteração, verificando se não quebrou nenhuma outra parte relacionada antes de contribuir o patch. Sempre devemos fazer o commit apenas de código funcional, para evitar quebrar o ambiente de trabalho de algum outro desenvolvedor ou de adicionar bugs obscuros no software. Ferramentas de integração contínua e de TDD poderão ser adotadas pela comunidade para garantir essa qualidade no código.
Pedir ajuda no fórum de suporte
A primeira vista pode nem parecer mas um simples pedido de ajuda no fórum de suporte pode contribuir muito para a comunidade e para o projeto:
- Sua dúvida pode ser a dúvida de alguém que não teve coragem de perguntar;
- Ao ser respondida, outras pessoas analisaram a dificuldade enfrentada e sugeriram alguns passos que podem vir a:
- complementar a documentação oficial ou;
- ajudar na identificação de um bug até então desconhecido;
- Estimula a participação de outros usuários a darem seu feedback.
Para pedir ajuda, utilize o fórum Suporte.
Ajudar pessoas com dificuldades no fórum de suporte
Ajude a responder dúvidas no fórum de suporte. Isso evita que novos (e antigos) usuários fiquem frustrados e que desistam do i-Educar. Lembre-se: o feedback deles é essencial na identificação de novos bugs e para identificação de pontos falhos na documentação e na usabilidade do software.
Transformar as dúvidas mais frequentes do fórum de suporte em itens do FAQ
Com o tempo, as mesmas dúvidas aparecerão no fórum de suporte. Ao identificar uma dúvida frequente, atualize o FAQ criando uma nova entrada com a pergunta/dúvida como título e com uma resposta para a mesma.
Contribuir com a documentação
Uma boa documentação é determinante para o sucesso de um projeto de Software Livre. Contribua com a documentação, seja ela técnica ou de uso do software. Padrões para a criação de documentação ainda serão definidos mas não espere por eles: contribua! Tenha um cuidado a mais com o português e tente ser o mais simples possível.
Nossa documentação é toda centralizada nesse wiki. Qualquer um com uma conta na comunidade i-Educar no Portal do Software Público pode alterar a documentação, seja para corrigir erros ou para contribuir com mais um tópico. Basta utilizar o mesmo login e senha, no prompt que aparece após clicar no link Entrar localizado no menu superior deste wiki.
Organize eventos, dê palestras
Organize algum evento: um code sprint, seminário, mesa redonda, desconferência (não importa o tamanho!) e divulgue/explique o que é o i-Educar. Convide educadores! Divulgue sua palestra no weblogger da página da comunidade i-Educar no Portal do Software Público e atualize a página wiki de Eventos? com o tema de sua evento (título da palestra, objetivo, etc) e data com um link para maiores informações (como local do evento, valor da entrada, entre outras).
Tem algum evento interessante próximo aceitando propostas de palestras? Crie uma e envie. Você irá se divertir compartilhando conhecimento e terá um feedback muito bom! Depois, compartilhe seus slides/anotações fazendo upload de seu material em seu blog ou em sites como o Slideshare e atualize a página wiki de Palestras?.
Criar material promocional
Tem algum aptidão em redação ou artes gráficas (ou uma imensa boa vontade)? Ajude a criar material promocional para o i-Educar como apresentações em slides, screencasts, cartilhas e badges para uso em sites. Procure licenciar este trabalho com alguma licença Creative Commons. Crie uma entrada na página wiki de Material para marketing apontando para o seu trabalho (pode ser um link direto de download ou apontando para uma página com os links de download).
Escrever posts no seu blog sobre o i-Educar
Escreva sobre o i-Educar. Diga o que pensa, o que gostaria que acontecesse, divulgue as boas novas. Coloque um link para o seu blog (mais especificamente para a página que lista os posts relacionados com o i-Educar) na página wiki Blogs?.
Discutir como o i-Educar pode ser melhorado no fórum de desenvolvimento e nos chats
Seja um cidadão i-Educar. Participe de nossa democrática comunidade no nosso fórum de desenvolvimento e nos chats que ocorrem de tempos em tempos dando sugestões e discutindo melhorias. Seja educado e evite responder de forma agressiva a insinuações (ou simplesmente as ignore). Use o bom senso!
Créditos
Algumas partes dessa documentação foram inspiradas no symfony "How to contribute" que inspirou-se em alguns trechos do Django Contributing to. Dois excelentes frameworks (PHP e Python, respectivamente) livres.
