Gestão de Mudanças
Processo simplificado de gestão de mudanças, releases e correções na plataforma Tolky
Este documento descreve o processo de gestão de mudanças, releases e correções da plataforma Tolky — abrangendo código, banco de dados e infraestrutura.
1. Objetivo deste Processo
Este processo busca equilibrar três pilares fundamentais:
Segurança
Garantir que atualizações não comprometam a estabilidade da plataforma.
Agilidade
Manter um fluxo rápido de desenvolvimento sem burocracia desnecessária.
Simplicidade
Operação leve e adequada para o ritmo de uma startup em crescimento.
2. Ambientes da Plataforma
A Tolky opera em três ambientes distintos, cada um com um papel específico no ciclo de desenvolvimento e entrega:
Development (DEV)
Ambiente de testes e validação interno. Funcionalidades recém-desenvolvidas são publicadas aqui para serem testadas pelo time de qualidade antes de avançar no fluxo.
Staging / Beta (STAGE)
Ambiente pré-produção que recebe apenas funcionalidades já validadas e aprovadas para a próxima virada para produção. O time de qualidade realiza testes end-to-end das entregas acumuladas neste ambiente. Em casos específicos, determinados clientes podem ter acesso a este ambiente para validação antecipada.
Produção (MAIN)
Ambiente final e estável, acessado por todos os clientes. Recebe apenas código já validado em STAGE, seguindo o ciclo de virada descrito neste documento.
Fluxo entre ambientes
DEV — Validação de funcionalidades
O time de qualidade testa cada funcionalidade individualmente no ambiente de desenvolvimento.
STAGE / Beta — Testes end-to-end
Funcionalidades aprovadas em DEV são enviadas para STAGE, onde o time de qualidade realiza testes integrados de todas as entregas acumuladas para a próxima virada.
MAIN — Produção
Após a validação completa em STAGE, as entregas são publicadas em produção durante a virada, seguindo o ciclo e os critérios descritos na seção 4.
Funcionalidades não devem ser enviadas diretamente para STAGE sem validação prévia em DEV. O ambiente STAGE deve conter apenas entregas já aprovadas para a próxima virada de produção.
3. Escopo das Mudanças
O processo de gestão de mudanças se aplica a três categorias:
Código
Alterações em aplicação, APIs, integrações e lógica de negócio. Seguem o fluxo padrão de revisão e deploy descrito neste documento.
Banco de Dados
Criação ou alteração de tabelas, índices, migrations e ajustes em dados. Toda mudança em banco de dados é comunicada ao grupo de consultoria para conhecimento coletivo e medição de impacto antes da execução.
Infraestrutura
Alterações em servidores, pipelines, configurações de ambiente, DNS e escalabilidade. Toda mudança de infraestrutura é consultada com a consultoria de DevOps para avaliação de impacto e alinhamento antes da execução.
Mudanças em banco de dados e infraestrutura exigem comunicação prévia obrigatória com as respectivas consultorias — mesmo em situações de hotfix.
Comunicação por tipo de mudança
| Tipo de Mudança | Canal de Comunicação | Objetivo |
|---|---|---|
| Código | Pull Request + revisão do time técnico | Qualidade e rastreabilidade das alterações |
| Banco de Dados | Grupo da consultoria (comunicação obrigatória) | Conhecimento coletivo e medição de impacto |
| Infraestrutura | Consultoria de DevOps (consulta obrigatória) | Avaliação de impacto e alinhamento técnico |
4. Ciclo de Virada para Produção (STAGE → MAIN)
Este é o ritmo seguido pela Tolky para que todos saibam o que está indo para produção e quando.
Antes de enviar para STAGE: Apenas entregas realmente prioritárias e necessárias para a próxima virada são enviadas para STAGE. O PO e o time de qualidade são avisados previamente para manter o alinhamento sobre o que entrará na próxima virada.
O que é um freeze?
Freeze é o momento em que o ambiente de STAGE é congelado — nenhuma funcionalidade nova é enviada a partir desse ponto. O objetivo é garantir que o ambiente fique estável e previsível para que os testes end-to-end possam ser realizados com segurança, sem que novas alterações interfiram nos resultados. Durante o freeze, apenas correções críticas identificadas nos testes podem ser aplicadas.
Ciclo de virada (aproximadamente a cada 15 dias)
O ciclo de virada STAGE → MAIN ocorre em intervalos de aproximadamente 15 dias, sendo este o limite máximo entre uma virada e outra. Mesmo que as entregas acumuladas sejam pequenas, a virada acontece dentro desse prazo para manter a previsibilidade e o ritmo de entregas. Quando o freeze é iniciado, isso é comunicado formalmente aos clientes.
O prazo de 15 dias é um limite padrão, não uma data fixa. A virada pode acontecer antes, caso as funcionalidades já estejam validadas e prontas. A única exceção para ultrapassar esse prazo é em caso de bug identificado na validação pós-virada, onde o ciclo pode ser estendido em até 5 dias úteis para correção, conforme descrito nos critérios da virada.
Critérios da virada (STAGE → MAIN):
- Apenas em horário não comercial (das 18h às 7h) — a virada é realizada fora do horário de operação da plataforma para reduzir o impacto aos clientes. Considera-se horário não comercial o período entre 18h e 7h.
- Com o time de qualidade presente — logo após a virada, é realizado o checklist de validação para confirmar que as principais funcionalidades estão operando corretamente.
- Com aviso prévio aos clientes (mínimo 2 dias úteis) — a data da virada é comunicada com pelo menos 2 dias úteis de antecedência, junto com as informações do que será entregue (changelog).
- Em caso de bug identificado na validação — o time de qualidade e o time técnico avaliam e decidem entre corrigir o problema imediatamente ou realizar rollback. A decisão é comunicada aos clientes e ao restante do time. Nesse cenário, o prazo limite de 15 dias para a virada pode ser estendido em no máximo 5 dias úteis para correção. Caso a correção não seja concluída nesse prazo adicional, é realizada uma virada parcial — excluindo a funcionalidade identificada como causadora do erro — para não comprometer o ciclo de entregas.
Resumo do ciclo de virada:
- Apenas entregas prioritárias e validadas são enviadas para STAGE, com aviso ao PO e ao time de qualidade.
- O freeze de STAGE é iniciado e comunicado formalmente aos clientes.
- O time de qualidade realiza testes end-to-end em STAGE.
- O changelog é enviado aos clientes com o detalhamento das entregas (mínimo 2 dias úteis antes da virada).
- A virada STAGE → MAIN é executada em horário não comercial (18h–7h), respeitando o limite máximo de 15 dias entre viradas.
- Após a virada, o checklist de validação é executado com o time de qualidade presente.
5. SLAs e Bugs Críticos
Registro padrão: Problemas que não são críticos são registrados no sistema de gestão de tarefas (Linear / ClickUp) e seguem o processo de correção descrito neste documento — via patch (seção 6) ou release, conforme a natureza do problema. O tratamento segue exclusivamente o fluxo de gestão de mudanças (GMUD) descrito aqui, independentemente de processos de ITSM específicos de cada cliente.
O que é considerado crítico: Considera-se crítico aquilo que gera prejuízo financeiro ou interrompe a execução do objetivo do avatar ou da plataforma, sem qualquer forma de contenção ou solução paliativa viável imediata.
Fluxo de resposta a SLAs críticas
Quando uma SLA é identificada como crítica, o time técnico é acionado de forma direta e imediata. O objetivo é alarmar sobre a criticidade para que a investigação comece o mais rápido possível.
Acionamento direto
O time técnico é comunicado de forma direta (mensagem no grupo, ligação, menção) para garantir visibilidade imediata do problema. Notificações passivas não são suficientes para este tipo de situação.
Início da investigação
A investigação é iniciada imediatamente após o acionamento.
Feedback e resolução
A equipe responsável pela investigação (geralmente QA ou suporte) apresenta o feedback com a resolução proposta (código ou queries) ao PO. O PO é responsável por envolver as equipes necessárias, informar o cliente e definir prazos caso necessário. Antes da aplicação, é realizada a medição de impacto da correção para garantir que a solução não cause novos prejuízos à operação.
Hotfix em até 3 horas
O tempo máximo entre a identificação do problema e a correção em produção é de 3 horas.
O prazo de 3 horas contempla todo o ciclo: acionamento, investigação, correção e deploy do hotfix. Por isso o acionamento direto e imediato é essencial.
6. Tipos de Atualização
Esses termos são utilizados pela Tolky para classificar as entregas realizadas nos ambientes de DEV e STAGE (Beta) durante o ciclo de desenvolvimento. Eles ajudam a comunicar ao cliente a natureza do que está sendo entregue — por exemplo: “vamos subir um patch de correção do painel de atendimentos em beta para vocês validarem” ou “esse problema já está subindo junto com um patch em beta”. A virada de STAGE → MAIN (produção) não é classificada como um tipo específico — ela segue o ciclo descrito na seção 4 e inclui todas as entregas acumuladas no período.
Release (nova versão)
Atualização planejada que inclui novas funcionalidades, melhorias ou mudanças estruturais — como novos módulos, melhorias de desempenho ou de interface.
Patch (correção)
Correção de bug que não exige resposta imediata — como erros de regra de negócio, erros visuais ou comportamentos inesperados em funcionalidades específicas.
Fluxo de uma Release
Desenvolvimento
Implementação da funcionalidade ou melhoria.
Pull Request
Abertura de PR com descrição das mudanças e contexto.
Revisão de código
Revisão do código por outro membro do time técnico.
Publicação em DEV
A funcionalidade é publicada no ambiente de desenvolvimento para validação.
Testes em DEV
O time de qualidade testa a funcionalidade no ambiente DEV e valida o comportamento esperado.
Aprovação e publicação em STAGE
Após aprovação do time de qualidade, a funcionalidade é enviada para STAGE.
Testes end-to-end em STAGE
O time de qualidade realiza testes end-to-end em STAGE, validando a funcionalidade junto com as demais entregas acumuladas.
Todas as mudanças são registradas no changelog e incluídas na próxima virada STAGE → MAIN, seguindo o ciclo descrito na seção 4.
Fluxo de um Patch
Bug identificado
Identificação e documentação do problema no sistema de gestão (Linear / ClickUp).
Definição de destino
O PO, em conjunto com o cliente, avalia o nível de necessidade e impacto do problema e define se a correção será direcionada para DEV ou STAGE (Beta). Caso a decisão seja publicar diretamente em produção, o fluxo passa a ser tratado como hotfix (seção 7).
Correção
Implementação da correção na branch correspondente ao destino definido.
Pull Request
Abertura de PR com descrição do bug e da correção aplicada.
Revisão de código
Revisão por outro membro do time técnico.
Publicação em DEV e validação
A correção é publicada no ambiente DEV para que o time de qualidade valide que o problema foi resolvido sem causar regressões.
Publicação em STAGE
Após aprovação, a correção é enviada para STAGE e incluída na próxima virada STAGE → MAIN.
7. Hotfix
Hotfix é uma correção rápida aplicada diretamente em produção para resolver um problema identificado após uma virada. Diferente de um patch, o hotfix não aguarda o ciclo normal de virada — a correção é publicada diretamente em produção.
Quando é utilizado hotfix em vez de patch?
- O problema está ativamente impactando clientes ou operações em produção.
- Aguardar o próximo ciclo de virada (até 15 dias) causaria prejuízo financeiro, operacional ou de experiência inaceitável.
- Se o bug pode esperar sem impacto significativo, o fluxo de patch é o mais adequado.
Hotfix é utilizado apenas quando o problema não pode esperar o próximo ciclo de virada. O fluxo padrão de patch é sempre preferível quando o problema não é urgente.
Hotfix não crítico
Problema que não impede o uso da plataforma, mas precisa ser corrigido antes do próximo ciclo de virada.
Exemplos:
- Erro visual relevante
- Comportamento inesperado em uma tela
- Erro de validação secundário
- Falha em cobrança ou faturamento
Bug identificado
Identificação e registro do problema no sistema de gestão.
Criação de branch de hotfix
Criação de branch específica a partir da versão em produção.
Correção e PR
Implementação da correção e abertura de Pull Request com descrição do problema e da solução.
Revisão de código
Revisão rápida por outro membro do time técnico para garantir que a correção não introduza novos problemas.
Publicação em produção
A correção é publicada diretamente em produção. Versão exemplo: v1.0.102-prod
Validação em produção
Verificação de que o hotfix solucionou o problema sem gerar novos problemas. Essa validação deve ser concluída em até 3 horas. Caso a validação não seja concluída dentro desse prazo, ou se for identificado que o problema não foi resolvido ou que a correção gerou um novo problema, é realizado rollback para a versão anterior estável e a correção é ajustada.
Merge para branch principal
Após a validação bem-sucedida, a correção é integrada na branch principal (e nos ambientes STAGE/DEV) para manter o histórico atualizado e evitar regressões futuras.
Hotfix crítico
Problema que impacta diretamente a operação do sistema ou a experiência dos clientes.
Exemplos:
- Sistema indisponível
- Erro em login
- Erro grave em integração
- Falha que impede o uso da plataforma
Incidente identificado e acionamento direto
Identificação do problema e acionamento imediato do time técnico (mensagem, ligação, menção). Notificações passivas não são suficientes.
Investigação e correção imediata
Investigação da causa raiz e implementação da correção com prioridade máxima. Abertura de PR mesmo em situação de emergência.
Revisão rápida
Revisão expedita por outro membro do time técnico. Em casos extremos, a publicação pode ocorrer antes da revisão, mas o PR é revisado logo em seguida.
Publicação emergencial
A correção é publicada imediatamente em produção.
Validação em produção
Verificação de que o hotfix solucionou o problema crítico sem gerar novos problemas críticos. Essa validação deve ser concluída em até 3 horas. Caso a validação não seja concluída dentro desse prazo, ou se for identificado que o problema persiste ou que a correção gerou um novo problema crítico, é realizado rollback para a versão anterior estável e a correção é ajustada.
Registro e merge
Após a validação bem-sucedida, é feita a documentação do incidente, causa raiz e ações tomadas. Merge da correção para a branch principal, STAGE e DEV. Versão exemplo: v1.0.103-prod
O tempo máximo entre a identificação do problema e a correção em produção é de 3 horas. Esse prazo é o mesmo definido na SLA de bugs críticos (seção 5).
8. Regras de Segurança para Deploy
Para reduzir riscos em produção, as seguintes regras são seguidas:
Sempre usar Pull Request
Toda alteração passa por um Pull Request, mesmo em casos de hotfix.
Código sempre versionado
Toda publicação é registrada no Git antes de ser disponibilizada.
Rollback sempre disponível
Em caso de problema, é possível reverter rapidamente para a versão anterior estável.
Registro de mudanças
Toda mudança relevante é registrada no changelog.
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
9. Checklist antes de Deploy
Antes de qualquer publicação, os seguintes pontos são validados:
Se todos os pontos forem validados positivamente, a publicação pode ser realizada com segurança.
10. Versionamento e Fluxo de Decisão
Formato de versionamento
As versões geradas no processo de integração contínua (CI) seguem o formato:
vMAJOR.MINOR.<build>-<ambiente>
Exemplos por ambiente:
v1.0.42-stagev1.0.42-devv1.0.42-prod
| Parte | Controle | Descrição |
|---|---|---|
| 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 gerado automaticamente a cada execução do pipeline |
| <ambiente> | Fixo por pipeline | stage, dev ou prod conforme o ambiente de destino |
Os campos MAJOR e MINOR são controlados manualmente pelo time técnico. O número do build é incrementado automaticamente a cada execução do pipeline, registrando mudanças menores sem necessidade de alterar a versão manualmente.
Fluxo simplificado de decisão
| Situação | Tipo de atualização | Versão | Comunicação adicional |
|---|---|---|---|
| Nova funcionalidade | Release (MINOR) | X.Y+1.0 | — |
| Bug pequeno | 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 | — |
| Alteração em banco de dados | Conforme tipo acima | Conforme tipo acima | Grupo da consultoria (obrigatório) |
| Alteração em infraestrutura | Conforme tipo acima | Conforme tipo acima | Consultoria de DevOps (obrigatório) |