Gestão de Mudanças
Processo simplificado de gestão de mudanças, releases e correções na plataforma Tolky
Este documento define o processo de gestão de mudanças, releases e correções na plataforma. O objetivo é garantir segurança nas atualizações, mantendo agilidade no desenvolvimento e baixa burocracia, adequado para uma startup em crescimento.
1. Como levamos STAGE para produção (STAGE → MAIN)
Este é o ritmo que seguimos para que todo mundo saiba o que está indo para produção e quando.
Antes de mandar algo para STAGE:
Envie para STAGE só o que for realmente prioritário e necessário para a próxima ida à produção. Antes de enviar, avise o PO e o time de QA — assim todos ficam alinhados sobre o que vai entrar no próximo merge para produção.
A cada 15 dias:
Fazemos um freeze de STAGE e rodamos o merge STAGE → MAIN. Mesmo que as mudanças sejam pequenas, mantemos esse ciclo de 15 em 15 dias para todo mundo saber quando a próxima leva sobe. Quando entrarmos em freeze, isso deve ser comunicado formalmente aos clientes.
Quando fazemos a virada (STAGE → MAIN):
- Só em horário não comercial — para reduzir impacto em uso da plataforma.
- Com o time de QA presente — logo após a virada, fazemos um check das principais funcionalidades para validar que está tudo certo.
- Com aviso prévio aos clientes — comunicamos a data da virada e enviamos as informações (changelog) do que será entregue, para que todos saibam o que muda.
- Se um bug for encontrado no check — cabe ao time de QA e de devs decidir e executar: corrigir o erro na hora ou fazer rollback. Qualquer uma das decisões deve ser comunicada em seguida ao cliente e ao restante do time.
Resumo: prioridade ao enviar para STAGE + aviso ao PO e QA + a cada 15 dias, freeze e merge para MAIN, em horário não comercial, com QA presente e aviso + changelog aos clientes.
2. Versionamento
As versões geradas no CI seguem o formato:
vMAJOR.MINOR.<build>-<ambiente>
Exemplos por ambiente:
v1.0.42-stagev1.0.42-devv1.0.42-prod
| Parte | Controle | Uso |
|---|---|---|
| MAJOR | Manual | Mudanças grandes ou que podem quebrar compatibilidade (ex.: 2.0.x) |
| MINOR | Manual | Novas funcionalidades ou melhorias relevantes (ex.: 1.1.x) |
| <build> | Automático (CI) | Número do build (ex.: github.run_number). Cada build gera uma versão mais “minor” possível, sem precisar alterar MAJOR/MINOR. |
| <ambiente> | Fixo por pipeline | stage, dev ou prod conforme o deploy. |
O MAJOR e o MINOR são controlados pelo time (controle de versionamento). O número do build é usado para as mudanças mais minor possíveis — cada execução do pipeline incrementa esse número.
3. SLAs e bugs críticos
Registro no ITSM:
SLAs que não são críticas continuam sendo registradas no ITSM (Linear / ClickUp) no fluxo habitual.
O que é crítico:
Considera-se crítico aquilo que gera prejuízo financeiro ou interrompe a execução do objetivo do avatar ou da plataforma.
SLA para bugs ou comportamentos críticos:
O início da investigação de uma SLA crítica deve ocorrer em até 3 horas após o registro e a comunicação alertiva (chamar atenção) no grupo ou em outros canais.
Após a investigação:
É necessário dar feedback com a resolução proposta (código ou queries) para a correção. O time de devs deve ser envolvido para medir o impacto dessa alteração, para que a correção não cause mais prejuízos para a operação.
4. Tipos de Atualização
Release (nova versão)
Release é uma atualização planejada que inclui novas funcionalidades, melhorias ou mudanças estruturais.
Exemplos:
- Novas funcionalidades
- Melhorias de desempenho
- Melhorias de interface
- Novos módulos
Desenvolvimento
Implementação da funcionalidade ou melhoria na branch de desenvolvimento.
Pull Request
Abertura de PR com descrição das mudanças e contexto.
Revisão rápida
Revisão do código por outro membro da equipe.
Deploy em produção
Publicação da nova versão no ambiente de produção.
Prefira realizar o deploy fora do horário de pico e sempre registre as mudanças no changelog.
Patch
Patch é uma correção de bug que não exige resposta imediata.
Exemplos:
- Erro de regra de negócio
- Erro visual
- Comportamento inesperado em uma funcionalidade específica
Bug identificado
Identificação e documentação do problema.
Correção
Implementação da correção na branch adequada.
Pull Request
Abertura de PR com descrição do bug e da correção aplicada.
Deploy
Deploy junto à próxima release ou patch. Versão exemplo: v1.0.101-prod
5. Hotfix
Hotfix é uma correção rápida aplicada diretamente em produção para resolver um problema identificado após o deploy.
Hotfix deve ser utilizado apenas quando necessário. Sempre prefira o fluxo padrão de patch quando o problema não for urgente.
Hotfix não crítico
Problema que não impede o uso da plataforma, mas precisa ser corrigido rapidamente.
Exemplos:
- Erro visual relevante
- Comportamento inesperado em uma tela
- Erro de validação secundário
Bug identificado
Identificação e registro do problema não crítico.
Criação de branch de hotfix
Criação de branch específica a partir da versão em produção.
Correção
Implementação da correção.
Deploy
Publicação da correção em produção. Versão exemplo: v1.0.102-prod
Merge para branch principal
Integração da correção na branch principal para manter o histórico atualizado.
Hotfix crítico
Problema que impacta diretamente a operação do sistema ou dos clientes.
Exemplos:
- Sistema indisponível
- Erro em login
- Falha em cobrança ou faturamento
- Erro grave em integração
- Falha que impede uso da plataforma
Incidente identificado
Identificação e comunicação imediata do incidente crítico.
Correção imediata
Implementação da correção com prioridade máxima.
Deploy emergencial
Publicação imediata da correção em produção.
Teste rápido em produção
Validação rápida do comportamento após o deploy.
Registro do incidente
Documentação do incidente, causa raiz e ações tomadas. Versão exemplo: v1.0.103-prod
Tempo ideal de resposta: até 2 horas após a identificação do problema.
6. Regras de Segurança para Deploy
Para reduzir riscos em produção, as seguintes regras devem ser seguidas:
Sempre usar Pull Request
Toda alteração deve passar por um Pull Request, mesmo em casos de hotfix.
Nunca deployar código não versionado
Todo deploy deve estar registrado no Git antes de ser publicado.
Sempre ter rollback possível
Caso algo dê errado, deve ser possível voltar rapidamente para a versão anterior estável.
Registrar mudanças
Toda mudança relevante deve ser registrada no CHANGELOG.md.
Exemplo de CHANGELOG:
v1.1.100-prod
- nova automação de campanhas
- melhoria no painel de relatórios
v1.1.101-prod
- correção de erro no login
7. Checklist antes de Deploy
Antes de qualquer deploy, valide rapidamente:
Se todas as respostas forem positivas, o deploy pode ser realizado com segurança.
8. Fluxo Simplificado de Decisão
| Situação | Tipo de atualização | Versão |
|---|---|---|
| Nova funcionalidade | Release (MINOR) | X.Y+1.0 |
| Bug pequeno | Patch (PATCH) | X.Y.Z+1 |
| Bug urgente | Hotfix | X.Y.Z+1 |
| Bug que impede a operação | Hotfix crítico | X.Y.Z+1 |
9. Objetivo deste Processo
Este processo busca equilibrar três pilares fundamentais: