Pular para conteúdo

Fluxo do desenvolvedor

Este guia contém somente o necessário para desenvolver uma alteração e entregá-la por Merge Request. Build de imagens, deploy, Kubernetes e rollback são responsabilidades do fluxo operacional.

Repositório e branches

O repositório principal é:

https://gitlab.ecomsmart.com.br/ecomsmart/flow
  • temporariamente, crie branches de trabalho a partir da main;
  • envie MRs diretamente para a main, de qualquer branch de trabalho;
  • não envie alterações diretamente para main;
  • não faça push direto em develop ou main;
  • mantenha revisão, testes e título SemVer obrigatórios.

O modo atual é RELEASE_WORKFLOW=trunk, enquanto HML permanece desligada. develop continua disponível, mas não é etapa obrigatória da entrega. Para retomar o fluxo anterior depois de preparar HML, consulte versionamento e releases.

1. Criar a branch

Atualize a base local:

git switch main
git pull --ff-only origin main

Crie uma branch com nome descritivo:

git switch -c feat/nome-da-funcionalidade

Prefixos de branch como feat/, fix/, docs/ e refactor/ ajudam na organização, mas quem define a versão é o título do MR.

2. Implementar e testar

Faça alterações somente dentro do escopo da tarefa. Antes de enviar:

git status
git diff

Execute os testes do módulo alterado quando possível. Nunca adicione ao commit:

  • arquivos .env reais;
  • tokens, senhas ou kubeconfigs;
  • arquivos gerados pelo editor ou pelo sistema operacional;
  • credenciais copiadas de logs ou ferramentas locais.

Crie o commit e envie a branch:

git add CAMINHOS_ALTERADOS
git commit -m "descrição objetiva da alteração"
git push -u origin NOME_DA_BRANCH

3. Abrir o Merge Request

No GitLab, abra um MR da sua branch para main. O título é obrigatório e define o próximo número de versão:

Título do MR Quando usar Incremento
fix: ... correção compatível patch: 0.0.2 para 0.0.3
feat: ... nova funcionalidade compatível minor: 0.0.2 para 0.1.0
breaking change: ... mudança incompatível major: 0.1.0 para 1.0.0
feat!: ... ou fix!: ... forma curta para incompatibilidade major

Exemplos válidos:

fix: corrigir retorno do onboarding
feat: adicionar filtro de campanhas
breaking change: alterar contrato da API de mensagens

Títulos como ajustes, correção ou minha tarefa serão recusados pela pipeline. O prefixo do commit não substitui o prefixo do título do MR.

Na descrição do MR, informe:

  • o problema ou objetivo;
  • o que foi alterado;
  • como a alteração foi testada;
  • impactos, migrations ou configurações necessárias;
  • imagens ou evidências quando houver mudança visual.

4. Acompanhar a pipeline

A primeira verificação é release_title_policy. Se ela falhar, corrija o título do MR; não é necessário criar outro commit.

Depois são executados três jobs paralelos python_unit_tests, distribuindo os sete módulos Python entre eles. Outros jobs aparecem somente quando relevantes:

  • release_versioning_tests: quando as regras de versão mudam;
  • kubernetes_manifests: quando arquivos de CI/CD ou Kubernetes mudam.
  • docs_build: quando a documentação ou sua configuração de publicação muda.

kubernetes_manifests apenas valida e renderiza arquivos YAML. Ele não acessa nem modifica o cluster.

O job flow_build_all_images não deve aparecer no MR. Build, publicação de versão e deploy acontecem depois do merge.

Se um teste falhar:

  1. abra o job com erro e localize a primeira falha real no log;
  2. corrija a branch local;
  3. execute o teste afetado localmente;
  4. faça commit e push na mesma branch;
  5. aguarde a nova pipeline do MR.

Não use retry para esconder uma falha determinística. Retry é adequado apenas quando houver evidência de falha transitória de rede ou infraestrutura.

5. Revisão e merge

Antes do merge, confirme:

  • título no formato correto;
  • pipeline obrigatória verde;
  • conflitos resolvidos;
  • discussões da revisão resolvidas;
  • nenhuma credencial ou arquivo local incluído;
  • descrição atualizada com a forma de validação.

Depois do merge, uma nova pipeline roda sobre o commit definitivo da main. Ela repete os testes, constrói as imagens e cria a versão de produção. Essa repetição é esperada e garante que o artefato publicado corresponde exatamente ao estado integrado da branch.

O desenvolvedor não precisa iniciar jobs de build, publicação ou deploy. O deploy de produção exige aprovação manual de um responsável pelo ambiente.

Resumo rápido

Atualizar main
  -> criar branch
  -> implementar e testar
  -> push
  -> MR para main com fix:, feat: ou breaking change:
  -> corrigir eventuais falhas
  -> revisão
  -> merge

Para operação de releases, GitLab, Registry, Kubernetes, deploy e rollback, consulte CI/CD e Kubernetes do EcomSmart Flow.