Guia para contribuição¶

Para contribuir com o código da Empurrando Juntas, algumas boas práticas de programação devem ser seguidas. Esse guia apresenta como abrir bons merge requests, além de sugestões de boas práticas de programação adotadas pelo projeto.

Por onde começar¶

O ponto de partida para contribuir tecnicamente com o projeto é entrando no grupo aberto da comunidade no Telegram. Nesse grupo, estão presentes desenvolvedores, empresas e organizações que contribuem ou já contribuíram com a EJ. Uma vez no grupo, você pode entrar em contato com a equipe da Pencillabs para ser adicionado ao canal de comunicação de desenvolvimento.

A próxima etapa é subir o ambiente. O passo a passo está bem documentado no README.md do repositório. Caso você tenha alguma dificuldade ou dúvida que não esteja documentada, fique à vontade para perguntar nos canais da Pencil. Lembre-se:

Seja gentil e educada(o) ao fazer perguntas.
Faça perguntas inteligentes. Descreva o que você já tentou e pesquisou. Simplesmente dizer que “não funciona” não é uma pergunta inteligente.
Seja paciente. As pessoas da equipe irão te responder assim que possível.
Sempre priorize a comunicação nos grupos. Evite contactar pessoas da equipe no privado.

Estudando a aplicação¶

Com o ambiente local configurado, está na hora de estudar a arquitetura do projeto e suas peculiaridades. Antes de partir para o código, recomendamos que você leia o guia de usuário para exercitar conceitos básicos como: o que é uma conversa, como funciona a jornada de participação e como os dados são coletados e processados. Em seguida, recomendamos a leitura do guia de desenvolvimento. Nele, você terá uma visão geral de como a EJ funciona internamente, o que irá facilitar o estudo do código-fonte.

Escolhendo uma issue¶

o ponto de partida para começar a contribuir com o código-fonte é o board de planejamento. Nele, o time prioriza o que será desenvolvido durante a sprint. A EJ utiliza o framework OKR para definir objetivos e resultados-chave que guiam a priorização do trabalho. Definido o escopo, o time se dedica durante as próximas duas semanas para executá-lo. O board, também conhecido como kanban, apresenta o andamento do trabalho ao longo dessas duas semanas.

Nossa recomendação é que você discuta com o time qual deve ser a sua primeira issue. Nós faremos o esforço de sempre manter o board atualizado e com as issues devidamente categorizadas, mas quem realmente sabe o que é prioridade são as pessoas que já estão trabalhando no projeto. É papel delas te integrar ao fluxo da sprint e dar orientações em relação às boas práticas de contribuição.

Trabalhando na sua issue¶

A EJ utiliza duas branchs principais.

develop: branch de desenvolvimento que recebe as contribuições do time durante a sprint.
prod: branch de produção, que é atualizada a cada 15 dias com uma nova release do projeto.

Para começar a trabalhar na sua issue, você criará uma nova branch a partir da develop. A sua branch deve ter no nome o ID da issue que você está desenvolvendo. Todo o desenvolvimento deve ser feito utilizando o ambiente configurado via Docker, conforme o README.md do projeto. Seja curioso, explore o código, estude o que você não souber e se mesmo assim você não conseguir avançar, faça suas perguntas nos canais do projeto.

O time segue algumas regras que aceleram a revisão e aprovação dos merge request.

Testes unitários e de integração¶

Toda alteração no backend que adicione novos comportamentos precisa ser testada de forma unitária. Alterações em views existentes ou novas, precisam ter testes de integração. O projeto utiliza a ferramenta pytest para testes unitários e de integração.

Testes de aceitação¶

Toda alteração no fluxo de participação (criação/edição de conversa e página de participação), precisa ter um cenário de testes implementado com a ferramenta Cypress.

BEM CSS¶

A EJ utiliza SASS para implementar o estilo das páginas HTML. Para definição das classes, o time segue a metodologia BEM.

HTMX¶

Algumas telas da EJ precisam realizar requisições de forma assíncrona para o backend. A EJ utiliza a ferramenta HTMX para isso.

Responsividade¶

Toda issue que envolva frontend precisa garantir responsividade para diferentes tamanhos de tela. Algumas práticas que adotamos:

Sempre utilizar a medida rem para definir a medida de blocos da página.
Sempre utilizar a medida em para tamanho de fontes.
Utilizar como tamanho mínimo de tela, a dimensão de 360px.
Priorizar o uso de flexbox e grid layout para posicionar e alinhar elementos na tela.
Evitar utilizar padding e margin para posicionar elementos na tela.
Nunca definir cores de forma hardcoded nos arquivos scss. Sempre reutilizar as variáveis do arquivo _config.scss.
Caso você tenha alguma dúvida sobre o protótipo de alta fidelidade relacionado à sua issue, pergunte para a pessoa mentora ou a designer.

Estilo de código¶

Toda linguagem tem sua forma de resolver problemas, não é diferente com Python. Sempre tente implementar a solução da issue da forma mais “pythonica” possível. A equipe adota a ferramenta Black como padrão de formatação de código Python.

Boas práticas de programação¶

O Django segue a arquitetura MVT (model-view-template). É papel do desenvolvedor refletir criticamente sobre a responsabilidade de cada uma dessas camadas. De modo geral, temos as seguintes convenções:

Regras de negócio devem ser implementadas na camada de models. Em caso de dúvidas, discuta com o time qual parte da sua issue é regra de negócio.
A camada de templates precisa executar o mínimo de lógica possível. É papel da view alimentar o template com as variáveis necessárias para a correta renderização.
O papel da camada de visualização é conectar templates com models. Ela deve receber uma requisição HTTP e responder o template apropriado. Tenha cuidado com a coesão ao implementar código na camada de visualização. Dê preferência para class-based views ao implementar fluxos complexos de requisição.
Evite definir arquivos com nome utils ou helpers se o código vai ser utilizado em uma única classe. Melhor manter o código dentro da classe que vai utilizá-lo.
Evite overengineering. Busque sempre a implementação mais simples possível, que respeite a arquitetura do Django e os princípios SOLID. Deixe para resolver um problema futuro quando ele acontecer.
Signals, middlewares, decorators e outros recursos intermediários e avançados do Django e do Python devem ser utilizados com cautela. Quanto mais genérica a implementação, mais complexa a manutenção.

Documentação¶

A EJ utiliza o projeto Sphinx para construir tanto o guia de usuário quanto de desenvolvimento. Fique atento se a sua issue exige atualizar a documentação. Caso sim, você precisará atualizar os arquivos .rst da documentação com as mudanças propostas. A documentação está disponível no diretório docs do repositório.

Traduções¶

A EJ utiliza o suporte nativo do Django para internacionalização. Todas as strings precisam estar em inglês e utilizarem o suporte de tradução do Django. No arquivo locale/pt_BR/LC_MESSAGES/django.po ficam as traduções do inglês para o português. Leia mais em Internalização e tradução.

Abrindo um merge request¶

Para que a sua contribuição seja disponibilizada no ambiente de homologação e depois em produção, é preciso passar pela etapa de revisão. Essa etapa consiste em abrir um merge request no Gitlab, da branch que você criou para desenvolver a issue para a develop. O revisor do seu merge request será alguém mais experiente do time e você pode solicitar a revisão no canal de comunicação para desenvolvimento.

O time segue algumas convenções para abertura de merge rquests.

Revise o seu merge request¶

A primeira convenção (que é praticamente uma regra) é que você revise o seu merge request antes de solicitar um revisor. Isso é importante para que você corrija problemas e erros de falta de atenção que ocorreram durante o desenvolvimento. Aproveite esse momento e releia o guia de contribuição para verificar se alguma das boas práticas não foi seguida. Uma forma prática de fazer essa “auto revisão” é abrir o MR como draft. Com o MR em draft, os revisores sabem que ele não está pronto para revisão, mas você poderá utilizar o painel do Gitlab para verificar quais mudanças serão adicionadas ou removidas. Quando você julgar que o MR está pronto, remova o draft e solicite um revisor no canal.

Teste o seu merge request¶

Um merge request que quebra os testes não será revisado, a não ser que a branch develop também esteja quebrada. Um merge request que altera o backend e não adiciona novos testes, não será revisado. Um merge request que altera a jornada de participação e não adiciona novos testes, não será revisado. Você pode acompanhar a execução do pipeline de integração contínua na página do seu MR. O Gitlab irá informar se alguma etapa da esteira de integração e deploy falhou.

Aprovando o seu merge request¶

Quando o seu merge request for aprovado, nossa esteira de deploy contínuo será ativada e o ambiente de homologação será atualizado com a sua contribuição 🎉🎉.