CONTRIBUTING.md

Guia de contribuição

Ficamos muito felizes que você está lendo este guia de contribuição, sempre precisamos de pessoas voluntárias que acreditem na ideia e queiram contribuir com o projeto.

Se você ainda não fez isso, junte-se também a nós nos nossos grupos abertos do Telegram ou do Discord e participe das discussões. Não hesite em nos procurar para tirar todas as suas dúvidas.

Antes de começar

Aqui estão alguns recursos importantes que você deve estar ciente antes de começar:

• Manual de dados abertos para desenvolvedores te explicará um pouco sobre o que são e os principais conceitos por trás dos dados abertos.
• Materiais de Estudo materiais de estudo sobre orçamento público e controle social.

Reportando bugs

Você encontrou um bug?

• Sugestões de melhoria são rastreadas através de issues e pull requests no GitHub. Verifique se nenhuma issue ou pull request foi criada por outra pessoa com o mesmo bug.
• Se não, crie uma issue explicando o problema e adicionando novas informações detalhadas que ajudem a reproduzir o problema.

Sugerindo melhorias

Você é mais que bem-vinda(o) a sugerir melhorias. Pedimos apenas que tente incluir o máximo de detalhes possíveis e que verifique se nenhuma issue ou pull request já foi criado por outra pessoa com a mesma sugestão.

Caso seja algo novo, você tem duas alternativas:

• Criar uma nova issue
• Compartilhar a sua sugestão com outros participantes e mantenedores do projeto em nosso grupo no Telegram

Em ambos, tente usar uma linguagem clara, e com o máximo de detalhes. Qual a motivação, qual problema resolveria e possíveis desafios, por exemplo, são importantes para entender o que você precisa. Esse é um projeto de código aberto, mantido por voluntários. Frequentemente precisamos escolher bem o que vamos fazer com os recursos que temos. :)

Criando pull requests

Você decidiu contribuir para o projeto! Yay!

Para contribuir com análises, escolha um dos datasets disponíveis e crie ou incremente um Jupyter notebook com suas análises.

Faça um fork do projeto e crie uma nova branch. Mais detalhes aqui.

Aqui algumas dicas:

• Caso decida trabalhar em alguma issue, comente na issue escolhida. Dessa forma, outras pessoas saberão que tem alguém trabalhando nela. Caso tenha ficado perdido ou com dúvidas, peça ajuda.

• Caso tenha visto algo pontual, como um typo ou algo que pode ser corrigido e testado rapidamente e não envolva mudanças estruturais, você é bem vindo a abrir um novo PR também.

• Antes de qualquer coisa, tente rodar o projeto localmente.

• Instale o pre-commit localmente com pre-commit install. Da próxima vez que você criar um commit as verificações serão executadas automaticamente. Caso exista alguma falha na formatação, você será informado e o commit só será permitido após correção - alguns linters como o isort já fazem a correção automaticamente mas ainda é necessário commitar novamente. Dessa forma mantemos o código mais arrumado.

• Ao criar um novo notebook siga o padrão YYYY-MM-DD-<github-user>-<titulo-da-analise>.ipynb.

• Gere um arquivo .py na pasta analysis/ e .html na pasta docs/notebooks/ a partir do seu notebook. Assim, poderemos revisar o seu código de maneira mais fácil e também visualizar o resultado. Para gerar o arquivo .py, execute:

jupyter nbconvert --to script analysis/YYYY-MM-DD-<github-user>-<titulo-da-analise>.ipynb

Para gerar o arquivo .html, execute:

jupyter nbconvert --to html analysis/YYYY-MM-DD-<github-user>-<titulo-da-analise>.ipynb

Ambos podem ser gerados a partir da interface do Jupyter Notebook.

• Rode os testes localmente com pytest. Além de ser uma boa prática, previne idas e vindas nas revisões.

• Adicione novos testes para novas funcionalidades ou bugs.

• Use o tempo presente nas mensagens do commit. Exemplo: "Adiciona funcionalidade" e não "Adicionada a funcionalidade".

• Atualize o README.md com os detalhes da mudança caso esta inclua uma nova base de dados ou um novo comando na CLI.

• Embora o código esteja escrito em inglês, por convenção, as mensagens de commit, comentários, pull requests, issues, e demais comunicações do projeto deverão ser escritas em português.

Sentiu falta de algo nesse guia? Conta pra gente!

Bem vinda(o) ao Dados Abertos de Feira!