Propósito
Este documento orienta engenheiros de software no desenvolvimento de projetos da CNN, garantindo qualidade técnica, consistência arquitetural.
Serve como guia de práticas obrigatórias e recomendações para desenvolvimento, revisão e entrega de código.
1. Orientações Gerais
Este documento, destinado a engenheiros de software, estabelece as diretrizes para o desenvolvimento de projetos na CNN Brasil. Ele visa assegurar a qualidade técnica e a consistência arquitetural, servindo como um guia de práticas obrigatórias e recomendações para o desenvolvimento, revisão e entrega de código.
Ao desenvolver um projeto, a prioridade é a qualidade e a precisão, não a velocidade de entrega. É obrigatório criar um documento no Notion arquivo, descrevendo o propósito do sistema e o passo a passo para configurar o ambiente de desenvolvimento local, incluindo dependências e variáveis de ambiente. Além disso, deve-se adicionar o link para essa página dentro do arquivo README.md no repositório.
A documentação completa do projeto, com dados, regras de negócio e referências técnicas, deve ser centralizada em um Documento de Definição e Design (DDD). Esta documentação é “viva” e deve ser atualizada com novas funcionalidades sempre que necessário.
É essencial seguir os padrões estabelecidos para a stack:
- Padrões de Código:
- PHP: PHPCS + PSR-12.
- WordPress: Padrões do WordPress e VIP, além dos padrões para o PHP.
- Node.js: Padrões internos e melhores práticas da comunidade (dependendo de cada fremework que será usado).
- Arquitetura: DDD, TDD e Clean Architecture.
- Convenções: Nomenclatura e semântica consistentes.
- Infraestrutura: Google Cloud Platform.
O código deve ser autoexplicativo. Comentários são permitidos apenas para descrever o propósito, entradas, saídas e pré-condições de classes ou métodos. Evite comentar a lógica interna, optando por nomes claros, métodos pequenos e estrutura legível. Use comentários apenas quando a intenção não puder ser expressa no código, como em ajustes de código legado ou regras de negócio complexas.
2. Fluxo de Desenvolvimento
O fluxo de trabalho deve ser sequencial:
- Estruturação da Documentação (DDD): Crie e estruture o DDD, centralizando todas as informações do projeto.
- Nessa etapa é necessário um trabalho em conjunto (Engenheiros e Arquiteto)
- Criação do Repositório: Crie o repositório no GitHub e configure o
README.mdcom as instruções de inicialização, sempre que necessário atualize o arquivo com mais detalhes. - Configuração Inicial: Inicialize o projeto, instalando dependências e realizando o setup básico.
- Estrutura de Pastas: Crie a arquitetura de pastas e módulos seguindo os padrões definidos.
- Preparação da Infraestrutura: Configure a infraestrutura necessária (banco de dados, servidores, etc.). Em projetos novos, a criação de um ambiente de
stagingé obrigatório! Garanta que a infraestrutura esteja pronta antes de iniciar o desenvolvimento de features que dependam dela. - Começar com TDD: Implemente testes unitários antes de desenvolver o código, seguindo os padrões estabelecidos, pode-se começar os testes usando os critérios de aceite como inicio.
- Testes de Integração: Crie testes de integração conforme a necessidade do projeto.
- Revisão do Autor: O próprio desenvolvedor deve revisar o código para garantir a qualidade inicial.
- Pull Request (PR) para Code Review: Submeta o PR para revisão técnica.
- Testes de Qualidade (QA): O time de QA fará os testes funcionais e a validação do sistema.
3. Revisões de Código (Code Review)
O objetivo do Code Review é garantir a conformidade do código com os padrões definidos pela CNN Brasil, prezando sempre pela estabilidade e escalabilidade dos projetos desenvolvidos.
Todo código escrito deve ser revisado por um humano, além da revisão automatizada por CI. A responsabilidade de manter o código seguindo todos os padrões é da Squad responsável pelo projeto.
Code Reviews devem ser feitos pela própria Squad, sempre por uma pessoa diferente da que escreveu o código.
Pull Requests para ambientes de testes que sejam aprovados em Code Review podem ser enviados a qualquer momento, porém PRs para ambientes de produção devem passar por Code Review de revisores específicos e devem seguir um cronograma de Code Review e Deploy.
Mais detalhes podem ser vistos em Fluxo de Code Review e Deploy para Produção
Pull Requests devem ser revisados em até 24 horas úteis após a abertura.
Caso um Pull Request tenha retornos vindouros de Code Review, deve-se voltar todo o fluxo de testes, independente do nível em que a tarefa esteja. Dessa forma, garantimos que as mudanças feitas não terão impactado a funcionalidade geral do projeto.
Responsabilidades do Engenheiro
- Seguir todos os padrões de código durante o desenvolvimento de sua tarefa
- Escrever testes para todos os novos módulos
- Ajustar testes existentes em módulos que tenham regras de negócio alteradas
- Executar testes manuais e automatizados
- Rodar o projeto nos linters e validadores de código do projeto
- Seguir os padrões de branch, commits e PRs
- Acompanhar a sua tarefa em toda a esteira de desenvolvimento, até produção
Responsabilidades do Revisor
O revisor deve:
- Baixar a branch e validar o fluxo funcional principal.
- Verificar a cobertura de testes e solicitar mais testes unitários ou de integração, caso necessário.
- Validar a aderência aos padrões de código e arquitetura.
- Sugerir melhorias estruturais ou de legibilidade.
- Em caso de detecção de bugs, seja por QA ou revisor, solicitar a criação de um teste que cubra o cenário.
4. Resolução de Conflitos
O autor do PR é o responsável por resolver os conflitos. Se houver dificuldades, deve-se acionar um revisor para apoio.
5. Integração Contínua e Deploy
- Se o QA ou o revisor solicitarem ajustes, o ciclo de revisão da PR deve ser reiniciado. O autor implementa as correções, a PR é reavaliada pelo Code Review e, em seguida, revalidada pelo QA.
- A PR só pode avançar para os ambientes de homologação ou produção após ser aprovada em todas as etapas.
- Todo PR deve passar pelo pipeline de CI/CD. Builds que falharem em testes ou verificações de segurança não podem ser aprovadas.
- Deploys devem seguir o fluxo estabelecido; é proibido o deploy direto na
master, salvo casos como hotfixes
6. Segurança
- Nunca faça commit de secrets (tokens, senhas, chaves, etc.).
- Revise dependências e pacotes de terceiros para verificar vulnerabilidades.
- Apenas adicione dependências externas ou bibliotecas em caso de extrema necessidade.
7. Integração entre QA e Desenvolvimento
Antes de entregar a feature para o time de QA, o time de desenvolvimento deve garantir:
- A implementação está de acordo com os critérios de aceite.
- Os testes unitários e de integração são executados com sucesso.
- A feature está estável e pronta para o QA.
- As alterações estão documentadas, incluindo endpoints, fluxos e pré-requisitos.
- Os erros críticos foram corrigidos.
- Foram adicionadas evidências à *user story *****de que a tarefa está funcional.
- Evidências podem ser vídeos ou print-screens da feature
O QA espera receber entregas estáveis, evitando retrabalho e bloqueios no fluxo de trabalho.