Skip to content

Latest commit

 

History

History
170 lines (131 loc) · 16.3 KB

CONTRIBUTING.md

File metadata and controls

170 lines (131 loc) · 16.3 KB
Raw

Português (BR) | English (US)

Contribuindo

O Querido Diário possui um Guia para Contribuição principal que é relevante para todos os seus repositórios. Este guia traz informações gerais sobre como interagir com o projeto, o código de conduta que você adere ao contribuir, a lista de repositórios do ecossistema e as primeiras ações que você pode tomar. Recomendamos sua leitura antes de continuar.

Já leu? Então vamos às informações específicas deste repositório:

Estrutura

Uma breve descrição da estrutura do repositório:

Diretório Descrição
.github Diretório com configurações do repositório para o GitHub
.github/workflows Configurações das GitHub Actions do repositório (fluxos de raspagens, deploy em produção, etc)
docs Diretório de arquivos de documentação do repositório (README, CONTRIBUTING, etc)
templates/spiders Diretório para templates de spiders pré-configurados no formato padrão do repositório
data_collection Diretório para projeto Scrapy de coleta de dados adaptado para as necessidades do Querido Diário
data_collection/gazette/database Diretório para o modelo de banco de dados
data_collection/gazette/resources Diretório para recursos adicionais: tabela de códigos IBGE dos municípios e esquema para validação dos dados de coleta
data_collection/gazette/spiders Diretório para as spiders dos municípios organizado por estado
data_collection/gazette/spiders/base Diretório de spiders base para padrões identificados em sites

Desafios

O principal desafio aqui é o de ter cada vez mais raspadores de sites publicadores de diários oficiais, visando atingir os 5570 municípios brasileiros. Utilizamos o Quadro de Expansão de Cidades para organizar as tarefas mais visualmente. Consulte-o para localizar tarefas relevantes com as quais você pode contribuir.

Para te ajudar a desenvolver, utilize as orientações da página "raspadores" disponível na documentação técnica do Querido Diário.

Labels e Milestones

As issues são marcadas com etiquetas (labels) e/ou agrupadas em metas (milestones), um recurso que serve para classificá-las quanto ao tipo, destacando diferentes aspectos de interesse que podem ter. Navegar na seção de labels e milestones facilita para encontrar uma issues mais do perfil do que gostaria de fazer.

Prioridades

Para garantir que nossos esforços estejam alinhados e focados em objetivos claros, definimos prioridades para o repositório. Nós endereçamos as issues e a fila de revisões seguindo esses critérios. Sua contribuição pode ser ainda mais valiosa quando alinhada com as prioridades.

Prioridade Descrição Onde encontrar
1 Manutenção de raspadores em produção maintenance
2 Adição de raspadores para municípios solicitados por alguma organização parceira podem ser marcadas com priority
3 Implementação de melhorias estruturais no repositório enhancement
4 Adição de spider base spider-base
5 Adição de raspador para município que é capital capitais
6 Adição de raspador para município da Amazônia Legal 100 cidades da Amazônia Legal
7 Adição de raspador para município que é populoso 100 cidades populosas
8 Adição de raspador não associado às metas sem label

Como escolher uma issue para fazer

O repositório tem tarefas bem delimitadas e, no geral, bem isoladas entre si. Isso é uma vantagem: permite à comunidade contribuidora ter boas opções de tarefas, com diferentes dificuldades, cobrindo de pessoas iniciantes às mais experientes.

Por isso, esta seção traz os tipos de raspadores do repositório, suas complexidades, quais etiquetas são usadas neles e quais seções da documentação serão mais necessárias para fazê-los.

Mas antes... A seguir, você terá a progressão da complexidade das tarefas do repositório, do básico ao avançado. Coisa que, em outras palavras, é quase como uma jornada guiada. Se você se propor a vivê-la, pode ter uma experiência interessante de crescimento técnico ;)

  1. Para município replicado
  • Não há complexidade, pois envolve apenas criar e preencher arquivos simples seguindo um padrão
    • Uma vez que não tem complexidade no código em si, a tarefa possibilita experienciar o básico (usar do git/GitHub, fazer a configuração do ambiente, rodar um raspador, conhecer o básico do log, etc), além do gostinho de ter uma contribuição feita sem muito estresse.
  • Onde encontrar essas tarefas? Elas são listas de municípios marcados com "boa primeira tarefa" (good first issue)
    • É uma modalidade de contribuição tão simples que, para valer o tempo de desenvolvimento e revisão, solicitamos que sejam enviados de 5 a 10 municípios por pull request. Deixe um comentário na issue avisando quais daquela lista vai fazer.
  • Seções úteis da documentação:
  1. Para município individual
  • No caso anterior, o "grosso" do código de raspagem já estava implementado e o novo raspador apenas complementa com alguns dados, por isso era tão simples. Porém, agora nesses casos, deve-se ser implementada toda a lógica de raspagem.
    • Será necessário exercitar conhecimentos como inspeção de páginas, uso de seletores e expressões regulares.
  • A dificuldade varia muito dependendo de como é o site a ser raspado e as barreiras que precisam ser superadas pelo raspador.
    • A grosso modo, pode-se dizer que os casos menos complexos é quando todos os diários são exibidos de uma vez em uma mesma página ou há uma paginação simples. A partir disso, a complexidade vai aumentando conforme uma ou mais barreiras vão aparecendo.
  • Onde encontrar essas tarefas? Elas são marcadas com spider e também com o nível estimado de dificuldade: dificuldade:baixa, dificuldade:media e dificuldade:alta
  • Seções úteis da documentação:
  1. Para sistema replicável
  • Se no caso 1 a tarefa era simples por usar um código já implementado, aqui o desafio é justamente criar esse código generalizado para o padrão do sistema que outros raspadores vão poder usar
    • Por isso, é considerada uma tarefa mais complexa: é um exercício de abstração, adiciona mais linhas de código e afeta múltiplos raspadores.
    • Mas também é a mais impactante: cada padrão integrado permite integrar dezenas de municípios, aumentando a cobertura do Querido Diário rapidamente.
  • Assim como o caso 2, a dificuldade varia muito e pelos mesmos motivos: depende das barreiras a serem superadas no site.
  • Onde encontrar essas tarefas? Elas são marcadas com spider-base
  • Seções úteis da documentação:

Contribua com revisão

Ao já ter desenvolvido todos os tipos de raspadores acima, experimente seguir contribuindo com o repositório por meio de revisões.

Como configurar o ambiente de desenvolvimento

Os raspadores são desenvolvidos usando Python e o framework Scrapy. Você pode conferir como instalar Python em seu sistema operacional e conhecer mais sobre o Scrapy neste tutorial. Com Python em seu computador, siga o passo-a-passo da configuração do ambiente de desenvolvimento:

Em Linux

  1. Faça um fork deste repositório e, com o terminal aberto em um diretório de preferência no seu computador, clone-o e acesse o novo diretório criado com o nome do repositório.
git clone <repositorio_fork>
cd querido-diario
  1. Crie um novo ambiente virtual - que manterá as execuções do projeto isoladas de seu sistema.
python3 -m venv .venv
  1. Ative o recém criado ambiente virtual
source .venv/bin/activate
  1. Instale as bibliotecas requeridas.
pip install -r data_collection/requirements-dev.txt
  1. Instale o pré-commit, uma ferramenta que, ao fazer o commit do código, verifica se ele se adequa aos padrões do projeto.
pre-commit install
  1. Seu ambiente de desenvolvimento está pronto! 🎉

Atenção: Estas etapas precisam ser executadas apenas na primeira vez que interagir com o projeto durante a preparação do ambiente. Depois disso, basta ativar o ambiente virtual (passo 3) cada vez que for utilizar ou contribuir com o repositório.

Em Windows

Pelo terminal do Windows

As instruções a seguir foram experimentadas em Windows 10 e 11. Lembre-se que caso deseje realizar uma integração com o repositório querido-diario-data-processing é preferível que a sua configuração de ambiente seja feita utilizando WSL.

  1. Instale o Visual Studio Comunidade . Ao abrir o terminal do instalado do Visual Studio, antes de instalar, você precisa selecionar na aba de Componentes Individuais "SDK do Windows 10" ou "11" (a depender do seu sistema) e "Ferramentas de build do MSVC v143 - VS 2022 C++ x64/x86 (v14.32-17.4)". Note que muitas vezes as versões Windows 10 SDK e MSVC v142 - VS 2019 C++ x64/x86 build tools serão atualizadas, portanto procure por itens similares em Componentes individuais para realizar a instalação (ou seja, mais novos e compatíveis com o seu sitema). Em Cargas de Trabalho, selecione “Desenvolvimento para desktop com C++”. Instale as atualizações, feche o aplicativo e siga os próximos passos.

  2. Siga todos os passos usados no Linux, com exceção do item 3. Nele, o comando deve ser:

.venv/Scripts/activate.bat

Observação: Nos comandos em Windows, o sentido da barra (/ ou \) pode variar a depender da utilização de WSL.

Utilizando WSL

Abra um novo terminal do Ubuntu e faça o clone do repositório forked do querido-diario.

Siga as instruções referentes À instalação utilizando Linux.

Este tutorial vai te ajudar na instalação e configuração do WSL na sua máquina Windows.

Formação automática de código

O projeto usa Black como ferramenta de automação para formatar e verificar o estilo do código e usa isort para organizar as importações. A integração contínua (CI) falhará se seu código não estiver adequadamente formatado.

Mas, se você seguiu as orientações para configurar o ambiente de desenvolvimento corretamente, especialmente instalando o pre-commit, é possível que você nunca precise corrigir a formatação manualmente. O pre-commit fará isso por você, já que executa antes de cada commit. Ainda, caso queira verificar todos os arquivos no projeto, use make format para evocar as ferramentas.

Observação: make não é disponibilizado nativamente em Windows, sendo necessário instalá-lo para a utilização sugerida.

Mantendo

As pessoas mantenedoras devem seguir as diretrizes do Guia para Mantenedoras do Querido Diário.

Revisão de raspadores

Toda vez que uma PR para raspadores é aberta, a lista de validações é acionada. É esperado que a pessoa contribuidora faça todas as verificações contidas na checklist, mas também é responsabilidade da pessoa revisora conferir os itens.

A checklist já cobre aspectos mais objetivos como o modelo do código, os campos obrigatórios e os arquivos de coleta-teste. Entretanto, outros aspectos devem ser levados em consideração na interação de revisão. Exemplos:

  • Padrão de código Python quanto ao uso de aspas duplas ("exemplo" / "exemplo='texto'")
  • Boas práticas no uso do XPath ou seletores evitando "voltas" desnecessárias
  • Legibilidade: se você teve dificuldade para entender algum trecho, verifique se este código pode ser melhorado
  • Pense a interação de revisão como uma progressão da evolução da pessoa contribuidora junto ao projeto, dando feedbacks como comentários nas linhas necessárias e apontando questões gerais ou reforçando questões pontuais.