Skip to content

Latest commit

 

History

History
102 lines (73 loc) · 11.5 KB

CONTRIBUTING.md

File metadata and controls

102 lines (73 loc) · 11.5 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 Configurações do repositório para o GitHub.
docs Arquivos de documentação do repositório (README, CONTRIBUTING, etc.).
e2e Testes end-to-end (👀).
src Diretório do código fonte. Contém arquivos principais da aplicação (index.html, styles.sass, etc.) e subdiretórios que organizam o código fonte.
src/app Diretório que organiza as funcionalidades da aplicação (diretivas, módulos, serviços, etc.)
src/app/data Conjuntos de dados constantes do projeto.
src/app/directives Comportamentos adicionais de elementos do projeto.
src/app/interfaces Interfaces de objetos de dados e algumas funções auxiliares.
src/app/modules Definições dos componentes visuais do projeto.
src/app/modules/components Componentes genéricos a serem usados no projeto (card, modal, etc.).
src/app/modules/layouts Estruturas genéricas a serem usadas no projeto (coluna, seção, etc.).
src/app/modules/pages Definições de forma e funcionalidade das páginas do projeto.
src/app/services Serviços de requisição e/ou entrega de dados/conteúdo.
src/app/stores Serviços de armazenamento de estado.
src/assets Arquivos de conteúdo estático (fontes, ícones, imagens e conteúdo textual).
src/assets/fonts Fontes tipográficas utilizadas no projeto.
src/assets/icons Ícones (geralmente SVG) utilizados no projeto.
src/assets/images Arquivos de imagem usados no projeto (em desuso, dar preferência a CDN).
src/assets/pages Arquivos de conteúdo textual a ser consumidos pelos serviços e inseridos nas páginas do projeto.
src/environments Configurações de ambientes de desenvolvimento e produção.

Como escolher a issue para trabalhar

Além das issues marcadas como good first issue e priority, como indicadas no Guia para Contribuição, também há algumas etiquetas importantes específicas do repositório do frontend:

  • backend dependency: Normalmente são issues mais complexas pois as demandas podem surgir no frontend mas necessitam do desenvolvimento em outros repositórios do projeto. Se as outras etapas do projeto ainda não foram desenvolvidas, não vale a pena investir tempo na issue.
  • ui/ux: Algumas demandas serão inteiramente dedicadas ao desenho de interfaces ou serão melhor endereçadas com esse esforço. Normalmente é melhor trabalhar nelas com experiência de frontend e também de design UI/UX, preferencialmente em equipe.
  • graphic design: Pode ser que ilustrações, imagens, ícones sejam necessários para algumas issues, se tiver experiência com esse tipo de trabalho, essas são pra você!

Ao escolher issues de desenho de interfaces ou de desenho gráfico, se atente aos estilos do projeto. Você também pode achar útil a documentação de design do frontend.

Como configurar o ambiente de desenvolvimento

O projeto utiliza Node.js e Yarn. Utilizamos também o nvm, um gerenciador de versão de node.js. Para saber a versão do node.js, a lista de dependências e suas versões, veja o arquivo package.json.

A seguir, veja como instalar todas essas ferramentas em seu sistema operacional.

Em Linux

  1. Instale o nvm.

  2. Com o nvm instalado, utilize-o para instalar a versão de node.js adequada para o projeto:

nvm install v16.2.0
  1. Ao instalar node.js, o gerenciador de pacotes npm é instalado junto. Utilize-o para obter o yarn:
npm install --global yarn
  1. Agora, no diretório raíz do projeto, instale as dependências utilizadas.
yarn
  1. Pronto! Agora você já pode começar a editar o código.

Executando o projeto com dependências externas

Parte das funcionalidades do frontend do Querido Diário dependem de recursos externos e será necessário configurá-los localmente ou utilizar os de produção (se possível) para modificar ou testar certas funcionalidades. As dependências são:

API pública

Para realizar buscas de conteúdo em diários, consultar dados de municípios cadastrados no QD, consultar dados de CNPJs e envio de emails de sugestões, é necessário interagir com a API do QD.

É possível utilizar a API de produção, principalmente se precisar de dados que demoram a ser coletados (e na API de produção já estão prontos para consulta) e o seu uso da API for de intensidade leve. Neste caso, não é necessário alterar nada no repositório, já configurado para acessar a API de produção.

Porém, em outros casos será necessário configurar localmente a API. Para isso, altere a constante API no arquivo src/app/constants.ts de 'https://queridodiario.ok.org.br/api' para 'http://0.0.0.0:8080' (ou 'http://localhost:8080'), e execute localmente (como instruído na documentação de configuração de ambiente da API) para consumir seus dados.

Se for necessário popular a API local com muitos dados, será necessário executar o fluxo completo do QD, da raspagem à disponibilização pela API. Nesses casos, consulte como configurar o Querido Diário de ponta-a-ponta.

Backend

As funcionalidades de busca e alertas do Querido Diário: Tecnologias na Educação dependem inteiramente do backend.

Não é possível utilizar o backend de produção. Para testar qualquer funcionalidade referente ao QD-Edu, será necessário configurar o backend localmente. Para isso, altere a constante educationApi no arquivo src/app/services/utils/index.ts de 'https://backend-api.queridodiario.ok.org.br/api/' para 'http://0.0.0.0:8000/api/' (ou 'http://localhost:8000/api/'), e execute localmente (como instruído na documentação de configuração de ambiente da API) para utilizar o backend local.

Se for necessário configurar a API e o backend do QD ao mesmo tempo, se atente ao uso correto de pods e containers para que os dois serviços possam ser levantados (dentro do mesmo pod com as duas portas abertas ou em pods diferentes) ou consulte como configurar o Querido Diário de ponta-a-ponta.

Mantendo

As pessoas mantenedoras devem seguir as diretrizes do Guia para Mantenedoras do Querido Diário. Assim como a documentação de design do frontend também traz informações importantes.