Guia de Workflow de Release — middag-io

Como releases funcionam com release-please, do commit a produção. Decisões de arquitetura: veja ADR-003.

Sumário

1. Como Funciona
2. Conventional Commits
3. O Fluxo de Release
4. Anotações de Versão
5. CHANGELOG-USER.md (Produtos Comerciais)
6. Ações Pós-Release
7. Fluxo de Hotfix
8. Cenários Comuns

1. Como Funciona

release-please monitora a branch main. Quando detecta conventional commits, cria (ou atualiza) uma Release PR que faz bump da versão e atualiza o CHANGELOG.md. O merge da Release PR cria uma tag e GitHub Release.

develop ──PR──> main ──push──> release-please
                                    │
                              Cria Release PR
                              (version bump + CHANGELOG)
                                    │
                              Merge da Release PR
                                    │
                          ┌─────────┴──────────┐
                          ▼                    ▼
                    GitHub Release        Git tag (X.Y.Z)
                    (auto-criado)              │
                                               ▼
                                    Workflow pós-release
                                    (build ZIP, deploy docs,
                                     notificar privatesatis)

2. Conventional Commits

Todo commit em main DEVE seguir o formato Conventional Commits:

Prefixo	Impacto Semver	Exemplo
`feat:`	minor (0.X.0)	`feat: add Stripe multi-entity support`
`fix:`	patch (0.0.X)	`fix: ISSNet certificate expiry check`
`feat!:` ou `BREAKING CHANGE:`	major (X.0.0)	`feat!: drop PHP 8.1 support`
`chore:`	nenhum (sem release)	`chore: update CI workflow`
`docs:`	nenhum	`docs: update API reference`
`ci:`	nenhum	`ci: add deploy step`
`refactor:`	nenhum	`refactor: extract email service`
`test:`	nenhum	`test: add unit tests for quotes`

Apenas feat: e fix: disparam version bump. Outros prefixos são registrados no CHANGELOG mas não criam uma release.

Scope (opcional)

Use scope para especificidade: feat(payments): add Stripe Connect support

3. O Fluxo de Release

Passo 1: Merge do PR em main

Desenvolvimento normal: feature/xyz → develop → PR para main.

Passo 2: release-please cria Release PR

Após merge em main, release-please:

Analisa mensagens de commit desde a última release
Calcula próxima versão (patch/minor/major)
Cria ou atualiza uma Release PR com:
- Bump de versão no arquivo de plugin/theme (via anotações x-release-please-version)
- CHANGELOG.md atualizado
- .release-please-manifest.json atualizado

Passo 3: Revisar e fazer merge da Release PR

Revisar o bump de versão e changelog
Para produtos comerciais: atualizar CHANGELOG-USER.md antes do merge
Fazer merge da Release PR

Passo 4: Pós-release automático

O merge dispara:

GitHub Release criado com tag
Workflow pós-release roda:
- Build de assets UI (se aplicável)
- Prefixação de vendor com Strauss (se aplicável)
- Criação do ZIP de distribuição
- Upload do ZIP no GitHub Release
- Trigger de rebuild do privatesatis
- Deploy de docs para Cloudflare Pages (se aplicável)

4. Anotações de Versão

release-please usa anotações x-release-please-version para encontrar e atualizar strings de versão.

Plugin WordPress

Em {plugin-name}.php:

php

 * Version: 5.0.16 // x-release-please-version
defined('MY_PLUGIN_VERSION') || define('MY_PLUGIN_VERSION', '5.0.16'); // x-release-please-version

Tema WordPress

Em style.css:

css

Version: 5.1.0 x-release-please-version

Em functions.php:

php

define('MY_THEME_VERSION', '5.1.0'); // x-release-please-version

Biblioteca PHP

Em composer.json — release-please trata isso nativamente para release type simple via version.txt.

5. CHANGELOG-USER.md (Produtos Comerciais)

Obrigatório para: wp-plugin-my-project, e qualquer produto com docs para usuário final.

Formato

markdown

# Changelog

## [5.0.17] - 2026-05-16

### Novo
- Suporte multi-entidade Stripe — gerencie pagamentos BR e Global separadamente
- Integração de webhooks HubSpot para sincronização automática de contatos

### Melhorado
- Geração de PDF de faturas 3x mais rápida

### Corrigido
- Entrega de e-mail para endereços Gmail em alguns casos específicos

Regras

Escrito na língua do usuário do produto (Português para produtos BR)
Sem jargão técnico ("refactor", "dependency bump", "fix N+1")
Agrupado por: Novo / Melhorado / Corrigido / Removido
Atualizado ANTES de fazer merge da Release PR
Site de docs público puxa deste arquivo

6. Ações Pós-Release

O que acontece automaticamente após o merge:

Ação	Trigger	Handler
GitHub Release + tag	Merge release-please	release-please action
Build ZIP dist	Output release_created	wp-plugin-post-release.yml
Upload ZIP no Release	Após build	softprops/action-gh-release
Trigger privatesatis	Após upload	repository_dispatch
Deploy docs	Output release_created	docs-deploy.yml

Intervenção manual necessária

Atualização do CHANGELOG-USER.md (antes do merge da Release PR)
Verificação de deploy em produção (após release)
Backport para develop se hotfix (veja seção 7)

7. Fluxo de Hotfix

Para correções críticas que não podem esperar o fluxo normal develop → main:

main ──branch──> hotfix/critical-fix
                        │
                   Fix + commit
                   (usar prefixo feat: ou fix:)
                        │
                   PR para main
                        │
                   Merge → release-please cria Release PR
                        │
                   Merge Release PR → tag + release
                        │
                   Também fazer merge do hotfix no develop

bash

# Criar hotfix
git checkout main
git pull origin main
git checkout -b hotfix/critical-fix

# Corrigir e commitar
git commit -m "fix: critical payment processing error"

# PR para main
gh pr create --base main --title "fix: critical payment processing error"

# Após merge + release: backport para develop
git checkout develop
git merge main
git push origin develop

8. Cenários Comuns

"Fiz merge em main mas nenhuma Release PR apareceu"

Verifique se os commits usam formato Conventional Commits
chore:, ci:, docs: não disparam releases
É necessário pelo menos um commit feat: ou fix:

"Quero fazer release mas só tenho commits chore"

Adicione um commit vazio com prefixo que dispara release:

bash

git commit --allow-empty -m "fix: trigger release for dependency updates"

"Quero pular uma release para um commit específico"

Commits sem prefixo feat:/fix: não disparam releases. Use chore: para mudanças que não devem gerar release.

"Quero forçar um bump de versão major"

Use sufixo ! ou footer BREAKING CHANGE::

feat!: drop PHP 8.1 support

BREAKING CHANGE: minimum PHP version is now 8.2

"O manifest do release-please está fora de sincronia"

Atualize .release-please-manifest.json manualmente:

json

{
  ".": "5.0.17"
}

Faça commit e push para main.

"Preciso fazer release sem passar pelo develop"

Use o fluxo de hotfix (seção 7). Nunca faça commit diretamente em main.

Guia de Workflow de Release — middag-io ​

Sumário ​

1. Como Funciona ​

2. Conventional Commits ​

Scope (opcional) ​

3. O Fluxo de Release ​

Passo 1: Merge do PR em main ​

Passo 2: release-please cria Release PR ​

Passo 3: Revisar e fazer merge da Release PR ​

Passo 4: Pós-release automático ​

4. Anotações de Versão ​

Plugin WordPress ​

Tema WordPress ​

Biblioteca PHP ​

5. CHANGELOG-USER.md (Produtos Comerciais) ​

Formato ​

Regras ​

6. Ações Pós-Release ​

Intervenção manual necessária ​

7. Fluxo de Hotfix ​

8. Cenários Comuns ​

"Fiz merge em main mas nenhuma Release PR apareceu" ​

"Quero fazer release mas só tenho commits chore" ​

"Quero pular uma release para um commit específico" ​

"Quero forçar um bump de versão major" ​

"O manifest do release-please está fora de sincronia" ​

"Preciso fazer release sem passar pelo develop" ​