GitLab

Sumário

• Introdução
• Definição das tecnologias
• Definição das arquiteturas
• Padrões de código
• Padrões de projeto
• Revisão dos MRs/PRs
• Ferramentas de devops
• Code Freeze
• Deploy
• Comunicação

Definição das tecnologias

A adequada seleção da stack tecnológica desempenha um papel fundamental em um projeto como AGES III, uma vez que estabelece o início do projeto e tornará a realização do escopo planejado executável, de forma a integrar todos do time. Para isso, é essencial adotar algumas melhores práticas para garantir o progresso do projeto. Abaixo estão algumas dessas melhores práticas que adotamos:

Entender as necessidades do projeto e o escopo a ser atendido. Para isso, é necessário avaliar os requisitos funcionais e não-funcionais, buscando selecionar tecnologias que atendam aos critérios, como qual será a plataforma principal de usuários, necessidade de consistência ou segurança, velocidade de resposta e etc.

Buscar se basear na escolha de tecnologias de projetos de sucesso com escopos semelhantes, tanto da AGES como na indústria. Isso é importante pois apesar da AGES ser um ambiente de experimentação, a falta de referências é um importante indicativo de uma escolha inadequada.

Definir tecnologias com ampla documentação disponível ou conteúdos disponíveis para estudo. Essa prática é fundamental não apenas para permitir que a equipe se aprimore durante o andamento do projeto, mas também para garantir que o desenvolvimento do projeto possa continuar fora da AGES e buscar soluções adequadas para o deploy dentro da organização.

Implementar tecnologias que o time tenha conhecimento prévio. É crucial adotar tecnologias nas quais a equipe já tenha conhecimento prévio, com foco especial nos membros AGES III e IV. Essa escolha visa facilitar o suporte aos demais membros da equipe e garantir que o time não dependa unicamente de poucas pessoas para a execução das tarefas.

Para garantir a familiaridade com as tecnologias é essencial conduzir uma pesquisa de competências dentro do time. Dessa forma, no nosso projeto conduzimos uma pesquisa no Google Forms, priorizando entender qual o nível de conhecimento, e desejo do time em trabalhar com as tecnologias indicadas.

Definição das arquiteturas

É fundamental estabelecer as arquiteturas a serem adotadas no frontend e backend o mais cedo possível ainda no andamento da sprint 0, seguido pela arquitetura de deploy. Para alcançar esse objetivo, busque seguir as melhores práticas a seguir:

Antes de definir as arquiteturas, é altamente recomendável estudar modelos e padrões já adotados em projetos na indústria ou em projetos anteriores da AGES. Aproveitar as melhores práticas da indústria e lições aprendidas de projetos anteriores pode economizar tempo e evitar já esperados, como a falta de compreensão e do objetivo da arquitetura escolhida.

As arquiteturas escolhidas devem ser facilmente compreensíveis por todos os membros da equipe, incluindo aqueles com menos experiência. Isso evita obstáculos na compreensão e execução das tarefas por membros menos experientes. Para isso, busque implementar uma arquitetura com compreensão mais simples e legível.

As arquiteturas devem ser autocontidas, o que significa que os componentes e módulos devem ser organizados de maneira lógica e independente. Isso simplifica a manutenção, aprimora a reutilização de código e facilita a resolução de problemas.

Em caso de desconhecimento prévio busque o quanto antes auxílio junto com os membros AGES IV ou o arquiteto da AGES, é extremamente necessário a definição o mais rápido possível, principalmente a arquitetura de deploy, busque utilizar as instâncias que deseja aprender e que não excedam o orçamento indicado.

Padrões de código

A adoção e definição precoce dos padrões de código desempenham um papel crucial no desenvolvimento de projetos, visando minimizar a ocorrência de erros e garantir a consistência ao longo do processo. Para atingir esse objetivo elencamos algumas dessas melhores práticas que adotamos a abaixo:

Estabelecer convenções para nomeação variáveis, diretórios, classes e outros elementos torna o código mais legível. Isso facilita a colaboração entre membros da equipe e a manutenção a longo prazo. Para isso opte por adotar algum estilo de nomenclatura em todo o código, como camelCase ou snake_case e evidencie exemplos para criação de variáveis mais explícitas.

Adotar padrões e diretrizes de estilização é essencial no desenvolvimento do frontend do projeto. Isso engloba não apenas a estética, mas também a usabilidade e manutenção do código, isso inclui garantir a responsividade esperada no escopo do projeto, evitar o uso de magic numbers e utilizar unidades de medida padronizadas, como "px", "em", "rem" ou demais que estiverem disponíveis pela tecnologia adotada.

Definir as bibliotecas e dependências a serem utilizadas no projeto desde o início é essencial para evitar conflitos e manter a consistência. Isso também contribui para a segurança e estabilidade do software, e mantém a aplicação padronizada.

A criação de testes unitários é fundamental para verificar a funcionalidade de componentes individuais do código, a fim de identificar problemas de maneira antecipada, contribuindo para a robustez e trazendo maior qualidade do software desenvolvido. Para isso, é essencial a definição de que cada tarefa desenvolvida só será aceita no MR juntamente com os testes realizados e aprovados.

Padrões de projeto

A adoção e definição de padrões de projeto é fundamental para evitar inconsistências na arquitetura definida e redundância de código. Para isso, é importante seguir as práticas a seguir:

Utilizar Git Flow é uma estratégia necessária para o gerenciamento de branches e organizar o desenvolvimento. Sempre opte por adotar e defina cedo qual padrão será utilizado, bem como qual padrão de nomenclatura deverá ser utilizado. Para garantir isso, é possível adotar soluções devops

Definir uma arquitetura de pastas é essencial para manter a estrutura do projeto organizada e fácil de entender, principalmente para membros menos experientes. Isso pode incluir a criação de diretórios separados para diferentes componentes, como controllers, models, views, componentes, páginas e entre outros, de acordo com a arquitetura do seu projeto.

Definir se serão aceitas tarefas com comentários em códigos é de suma importância para o desenvolvimento do projeto. Optar por não adotar comentários pode ser uma escolha válida, principalmente se os padrões de código estiverem sendo seguidos, o que resulta em código de maior qualidade e legível.

Revisão dos MRs/PRs

A revisão de MRs é uma das tarefas mais trabalhosas como AGES III, onde identificamos que testar a usabilidade feita, não aprovar tarefas com defeitos claros e fornecer feedback em casos de inadequações, boas práticas extremamente necessárias a serem seguidas. Além disso, se possível, inferir a necessidade de ter um approve adicional, ou seja, de dois membros AGES III ou IV, ou demais membros do time, aprovarem a tarefa realizada como uma boa prática a ser feita antes do MR ser aceito, isso busca promover maior contato do time com as atividades desenvolvidas e pode elevar uma prática de feedback maior entre o time. Em nosso projeto Globo Aplausos, pelo pequeno número de AGES III e IV, optamos pela revisão obrigatória de apenas de um AGES III, mas identificamos que o melhor cenário é aquele que mais membros se envolvam, quando possível.

Ferramentas de devops

As ferramentas abaixo de devops são algumas das que entendemos como boas práticas em utilizá-las ou necessárias em alguns casos.

Husky é uma ferramenta que auxilia a configuração de git hooks no projeto, permitindo a execução de scripts antes de commits e pushes, o que ajuda a garantir a qualidade do código. Habilitando a capacidade de que um commit e push só seja realizado em casos de regras a serem definidas, como testes passando, projeto buildando e demais ações a serem configuradas de desejo.

Docker é extremamente essencial para garantir o funcionamento da aplicação em todos os estágios de desenvolvimento, teste ou produção, caso não seja familiarizado, ou não saiba como configurar, busque saber o mais rápido possível antes da AGES III.

Ferramentas de testes automatizados E2E são boas práticas que sempre podem ser aplicadas, quando o escopo do projeto permite. Caso possível, sempre tente integrar os casos de testes realizados junto com o CI do GitLab, ferramentas como Selenium e Cypress possuem robusta documentação destes aspectos, e soluções como o Cypress Cloud permitem observar um histórico e gravações de testes de pipeline.

Empregar o CI/CD do Gitlab é uma boa prática que sempre é realizada na AGES, tente implementar o quanto antes a execução de alguns jobs nos repositórios. Para isso, primeiro é necessário a liberação de uma instância EC2 pelo arquiteto da AGES, porém, enquanto não ocorre, é possível criar uma instância free-tier em sua conta pessoal e deixar o setup pronto, caso não tenha familiaridade.

Code Freeze

Essa prática desempenha um papel crucial e necessário na AGES, especialmente na AGES III. Ela envolve a execução do deploy e revisão das tarefas no final da sprint, que é fundamental para a apresentação aos stakeholders. Portanto, é importante estabelecer um Code Freeze com pelo menos 3 dias de antecedência em relação às primeiras entregas, mas defina junto ao time e aos membros AGES IV. Isso é essencial, uma vez que o processo de deploy não está maduro nas primeiras sprints, o que pode se tornar um grande complicador além de tarefas não realizadas ou inadequadas para entrega.

Durante o período de Code Freeze, também é interessante que seja realizada uma reunião entre os AGES III e AGES IV do projeto, para analisar os Merge Requests restantes a serem margeados antes do deploy e testar o projeto para garantir as funcionalidades principais do sistema. Caso sejam encontrados bugs durante os testes, o momento da reunião pode servir como uma força tarefa para a resolução dos problemas antes do deploy.

Deploy

As boas práticas de deploy incluem fazer o quanto antes, e como primeira tarefa da AGES, a realização da arquitetura de deploy, esse estágio é muito importante, pois pode demorar várias sprints para que ocorra a liberação das instâncias, caso demore para enviar o diagrama ao arquiteto. Entretanto, para o deploy também é possível utilizar outras soluções free-tier, e até mesmo mais simples que a AWS para criar um setup automatizado de deploy, como Vercel ou Heroku.

Em caso de utilização da AWS é recomendado como uma boa prática a utilização de DuckDNS como forma de obter um domínio estático para sua instância, visto que os IPs públicos são modificados quando a instância é reiniciada. Dessa mesma forma, busque também implementar soluções para liberar uma url HTTPS, então estude como obter um certificado SSL e ferramentas de proxy e server, como Apache ou Nginx.

Comunicação

Como arquiteto responsável pelo projeto, é de extrema importância manter a comunicação com o time sobre os padrões que serão utilizados no projeto, dar feedbacks construtivos e auxiliar outros AGES no desenvolvimento de tarefas, também servindo como voz ativa para a definição de configurações e decisões no andamento do projeto. Outro ponto importante é estabelecer canais ativos de comunicação com os AGES IV do projeto, como por exemplo um grupo WhatsApp, para que sejam comunicadas mudanças importantes ou acontecimentos críticos no projeto.