Skip to content

Latest commit

 

History

History
103 lines (74 loc) · 8.45 KB

CONTRIBUTING.md

File metadata and controls

103 lines (74 loc) · 8.45 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:

Desafios

O principal desafio deste repositório é 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 o progresso do desafio. Consulte-o para localizar tarefas relevantes com as quais você pode contribuir.

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

Labels

As issues são marcadas com etiquetas, um recurso que serve para classificar issues de mesmo tipo, sinalizar se há algum empecilho ou direcionar a comunidade para tarefas mais do perfil delas. No geral, adotamos labels comuns a outros projetos de código aberto como "docs", "bug", "dependencies", mas também temos algumas específicas. Veja quais são na seção de labels

Metas do Repositório

Para garantir que nossos esforços estejam alinhados e focados em objetivos claros, definimos metas para o desenvolvimento e expansão do projeto. Estas metas são revisadas e atualizadas regularmente, refletindo as prioridades e os desafios que enfrentamos. Convidamos as pessoas contribuidoras a se familiarizarem com estas metas, disponíveis em nosso Quadro de Metas. Sua contribuição pode ser ainda mais valiosa quando alinhada com estas direçõ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.