Skip to content

Latest commit

 

History

History
82 lines (59 loc) · 5.56 KB

CONTRIBUTING.md

File metadata and controls

82 lines (59 loc) · 5.56 KB

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:

Algumas definições

Para que possamos falar a mesma língua, precisamos pactuar alguns termos importantes para o projeto:

  • Recursos: Onde dados podem ser encontrados e utilizados (banco Postgres, motor de busca Opensearch, etc.);
  • Serviços: Abstrações para acesso e modificação de recursos (OpensearchInterface, etc.) e outras ferramentas (ApacheTikaExtractor);
  • Tasks (ou tarefas): Unidade (ou etapa) de processamento que geralmente interage com os recursos para gerar suas saídas;
  • Pipelines: Conjunto de tarefas que cumpre um objetivo.

Estrutura

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

Diretório Descrição
.github Configurações do repositório para o GitHub.
docs Arquivos de documentação do repositório (README, CONTRIBUTING, etc.).
config Arquivos de configuração como variáveis de ambiente e palavras-chave de índices temáticos.
data_extraction Interfaces e implementações de serviços de interação com extratores de dados como o Apache Tika (texto).
database Interfaces e implementações de serviços de interação com banco como o Postgres.
docs Arquivos de documentação do repositório (README, CONTRIBUTING, etc.).
index Interfaces e implementações de serviços de interação com motores de busca como o Opensearch.
main Pipelines de processamento (para compreender inicialmente o funcionamento do projeto este é um bom ponto de partida).
segmentation Implementação de segmentadores do conteúdo textual de diários (ex: 1 diário de associação municipal -> N diários de municípios).
storage Interfaces e implementações de serviços de interação com armazenamento de objetos como o Minio.
tasks Diretório que contém as tarefas que serão executadas nos pipelines (definições das tarefas são encontradas em suas docstrings).
tasks/utils Utilitários para auxiliar as tarefas.
tests Testes unitários e de integração (👀).

Como configurar o ambiente de desenvolvimento

Para configurar o ambiente de desenvolvimento, é necessário o gestor de containers podman e Python (3.8+).

Em Linux

Antes de qualquer coisa, utilizamos pre-commit no projeto, então não se esqueça de configurar de um ambiente virtual Python com ele.

  1. Com o Python e podman instalados, na raíz do repositório, ative o ambiente virtual:
python3 -m venv .venv
source .venv/bin/activate
  1. Instale as dependências de desenvolvimento e instale o pre-commit:
pip install -r requirements-dev.txt
pre-commit install
  1. Agora vamos construir as imagens e montar o pod e os containers de recursos utilizados no processamento:
make build
make setup

Caso deseje que os dados processados sejam consumidos pela API ou Backend do Querido Diário localmente, acesse a documentação da configuração de ponta-a-ponta. Assim, a configuração deve ser feita usando:

make build
FULL_PROJECT=true make setup
  1. Pronto! Agora você já pode começar a editar o código e executar os pipelines.

Mantendo

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