CONTRIBUTING.md

Guia de Contribuição para o UnBrake

Como contribuir

Você pode contribuir com o projeto de várias formas: complementando a documentação, reportando bugs, adicionando funcionalidades, consertando bugs ou revisando PRs.

O primeiro passo é consultar nossas issues e pull requests em aberto.

Não há restrições entre issues reservadas para a equipe principal para desenvolvedores e comunidade.

Como utilizar as issues

Para acompanhar todo o projeto a UnBrake usa issues de tarefas. Para criar essas issues de forma fácil nós disponibilizamos um template no próprio github, responda todas as questões do template e continue o trabalho.

Além disso todas as issues devem ter:

• Todas as decisões, links, imagens e conversas relacionadas a issue em seu conteúdo.
• Sempre deve haver uma pessoa assinada a uma issue
• Utiliza labels para acompanhamento

Apenas as issues de tarefas devem ter:

• Um épico
• Uma estimativa
• Milestone associada

Criando suas branches

O primeiro passo para criar sua branch é definir um nome para ela, o padrão adotado pelo projeto é:

Nosso repositório segue alguns padrões para as issues:

• Nomes em portuguès
• São relacionadas a issues abertas
• Padrão de nome no seguinte formato: <número da issue>---

Propondo mudanças

Nesse ponto estamos considerando que você já tem uma issue e um branch para sua tarefa, uma fez que sua tarefa está pronta, testada e validada agora é hora de realizarmos um pull request.

Via github inicie o pull request utilizando o template fornecido, após isso as ferramentas de análise automática entram em ação e avaliam se sua contribuição está correta com relação a vários aspectos (estilo, linting, testes). Se a build da integração contínua for aprovada, não haja conflitos e sua branch esteja atualizada, o PR estará pronto para revisão de código por algum contribuidor.

Guia de Desenvolvimento

Subindo parte Web localmente

*Todos os comandos incluem o comando de build para envitar erros de iniciante mas não é necessário em todas as execuções

A aplicação pode ser executada localmente com o seguinte comando na raiz do repositório:

sudo docker-compose up --build

ou os serviços podem ser executados individualmente:

# Serviços disponíveis atualmente: frontend e api
sudo docker-compose up --build frontend

Executando checagens de código

Desde que o serviço do frontend já tenha sido construído (build executado pelo menos uma vez) no ambiente do usuário, algumas checagens serão executadas através de git hooks.

Como comportamento pre-commit, são executados os seguintes scripts: fix, check_lint e check_format, sem ser necessário nenhuma configuração ou execução manual de comandos por parte do usuário, tanto no frontend quanto na API.

Como pre-push, o comportamento difere um pouco entre o frontend e a API, no frontend são executados os testes e na API, além dos testes, a checagem padrão do django (script check). Da mesma forma que antes do commit, são executados sem ser necessário comandos por parte do usuário.

Caso alguma das checagens falhe, antes do commit ou antes do push, o procedimento é abortado. Como isso é feito através de git hooks, é possível evitar as checagens utilizando-se a flag --no-verify nos comandos do git, embora isso seja altamente desencorajado.

Frontend

Scripts disponíveis (frontend)

• check_all: Executa todos os outros scripts de checagem em sequência, na checagem de testes é executado o com coverage sem html
• check_lint: Checa por erros apontados pelo linter eslint
• check_format: Checa por erros de formatação apontados pelo prettier
• check_tests: Checa se todos os testes estão passando sem warnings ou mensagens de console utilizando o jest
• check_tests:coverage: Executa o que o check_tests faz, mas também gera arquivos de coverage para análise
• check_tests:coverage:html: Executa o que o check_tests faz, mas gera o relatório em HTML sobre as estatísticas de testes
• fix: Corrige automaticamente erros de formatação possíveis de serem consertados pelo eslint e pelo prettier

Execução de um script (frontend)

Uma das possíveis formas de se executar os scripts no frontend é executando o seguinte comando:

# 'npm' é o entrypoint
$ sudo docker-compose run --rm frontend run [nome_do_script]

API

Scripts disponíveis (API)

• check_all: Todos os outros scripts de checagem são executados em sequência, na checagem de testes é executado o com coverage sem html
• check: Executa checagem padrão do django por erros em geral
• check_lint: Checa por erros apontados pelo linter pylint
• check_format: Checa por erros de formatação apontados pelo flake8 ou falta de execução do autopep8
• check_tests: Checa se todos os testes estão passando, utilizando o pytest
• check_tests_coverage: Executa o que o check_tests faz, mas também gera arquivos de coverage para análise
• check_tests_coverage_html: Executa o que o check_tests faz, mas gera o relatório em HTML sobre as estatísticas de testes
• fix: Corrige automaticamente erros de formatação possíveis de serem consertados pelo autopep8

Execução de um script (API)

Uma das possíveis formas de se executar os scripts da API é executando o seguinte comando:

# 'manage.py' é o entrypoint
$ sudo docker-compose run --rm api [nome_do_script]

Local

A parte local funciona diferente das outras, como o entrypoint go não é personálizável, optamos por deixar transparente ao desenvolvedor a utilização do docker. Então o usuário já executa diretamente o script que quer sem fazer chamadas explícitas ao docker e ação desejada continua sendo executada num container.

Scripts disponíveis (Local)

Todos os comandos estão relativos a pasta unbrake-local Se a execução estiver demorando muito, pode ser que o container esteja sendo baixado, para acompanhar o progresso, é possível executar o comando sudo docker pull unbrake/local separadamente

• ./scripts/run: equivalente a se chamar go porém é executado dentro do container
• ./scripts/compile: gera o binário da parte local para Windows e Linux
• ./scripts/check_all: executa o check_format, check_lint e check_tests_coverage
• ./scripts/check_format: checa se a formatação do código está de acordo com a comunidade
• ./scripts/check_lint: checa por erros gerais no código
• ./scripts/check_tests: checa se os testes estão passando
• ./scripts/check_tests_coverage: checa se os testes estão passando e da informações de cobertura
• ./scripts/check_tests_coverage_html: checa se os testes estão passando e gera informações de cobertura em html
• ./scripts/fix: corrige erros fáceis de serem automaticamente corrigidos

CodeClimate CLI

O codeclimate irá checar algumas coisas já checadas localmente e outras menos importantes, que só serão exigidas de serem consertadas antes do do pull request, ao invés de em cada commit. Para executar as ferramentas do codeclimate localmente, execute o seguinte comando:

sudo docker-compose run -e CODECLIMATE_CODE=${PWD} --rm codeclimate analyze

Nesse caso foi usado o comando analyze, a lista completa de comandos pode ser encontrada aqui, ou então executando o serviço disponível no docker-compose sem passar nenhum comando em específico.

Scripts úteis

Existem alguns scripts úteis para realizar debug e/ou auxiliar no desenvolvimento na pasta utils na raiz do projeto.

Não esquecer de instalar as dependências necessárias para o script que irá utilizar

Scripts disponíveis (utils)

get_mqtt_data

Obtém todos os dados enviados em subchannels de unbrake/galpao/

Exemplo de uso:

MQTT_KEY='minhakeyquetempermissãodefazeroqestoutentando' MQTT_HOST='unbrake-hom.ml' python3 get_mqtt_data.py

get_mqtt_data

Envia dados aleatórios simulando dados de todos os principais sensores abrangidos pela aplicação

Exemplo de uso:

MQTT_KEY='minhakeyquetempermissãodefazeroqestoutentando' MQTT_HOST='unbrake.ml' python3 send_mqtt_mock_data.py