Pular para o conteúdo principal

Gerenciamento de Lançamentos

Versionamento (Versionamento Semântico)​

O projeto segue Versionamento Semântico (SemVer) com o formato MAJOR.MINOR.PATCH:

  • MAJOR versão (x.0.0): Quando você faz alterações de API incompatíveis
  • MINOR versão (0.x.0): Quando você adiciona funcionalidade de forma compatível com versões anteriores
  • PATCH versão (0.0.x): Quando você faz correções de bugs compatíveis com versões anteriores

Lista de Verificação Pré-Lançamento​

Antes de lançar uma nova versão, certifique-se de que você concluiu o seguinte:

  • Todas as alterações foram confirmadas e enviadas para o branch vMAJOR.MINOR.x.
  • O número da versão foi atualizado em package.json (use scripts/update-version.sh para sincronizá-lo entre os arquivos).
  • Todos os testes foram aprovados (no modo de desenvolvimento, local, docker e podman).
  • Inicie um contêiner Docker com pnpm docker:up e execute scripts/compare-versions.sh para verificar a consistência da versão entre o ambiente de desenvolvimento e o contêiner Docker (requer que o contêiner Docker esteja em execução). Este script compara as versões do SQLite apenas pela versão principal (por exemplo, 3.45.1 e 3.51.1 são consideradas compatíveis) e compara exatamente as versões do Node, npm e Duplistatus.
  • A documentação está atualizada; atualize as capturas de tela (use pnpm take-screenshots)
  • As notas de lançamento foram preparadas em documentation/docs/release-notes/VERSION.md.
  • Execute scripts/generate-readme-from-intro.sh para atualizar README.md com a nova versão e quaisquer alterações de documentation/docs/intro.md. Este script também gera automaticamente README_dockerhub.md e RELEASE_NOTES_github_VERSION.md.

Visão Geral do Processo de Lançamento​

O processo de lançamento recomendado usa GitHub Pull Requests e Releases (veja abaixo). Isso oferece melhor visibilidade, capacidades de revisão e dispara automaticamente compilações de imagens Docker. O método de linha de comando está disponível como uma alternativa.

Este é o método preferido, pois fornece melhor rastreabilidade e dispara automaticamente compilações do Docker.

Etapa 1: Criar Pull Request​

  1. Acesse o repositório duplistatus no GitHub.
  2. Clique na aba "Pull requests".
  3. Clique em "New pull request".
  4. Defina o branch base como master e o branch compare como vMAJOR.MINOR.x.
  5. Revise a prévia das alterações para garantir que tudo esteja correto.
  6. Clique em "Create pull request".
  7. Adicione um título descritivo (por exemplo, "Release v1.2.0") e uma descrição resumindo as alterações.
  8. Clique novamente em "Create pull request".

Etapa 2: Mesclar a Solicitação de Pull​

Após revisar o pull request:

  1. Se não houver conflitos, clique no botão verde "Merge pull request".
  2. Escolha sua estratégia de merge (normalmente "Create a merge commit").
  3. Confirme o merge.

Etapa 3: Criar Versão no GitHub​

Após a conclusão da mesclagem, crie uma versão no GitHub:

  1. Acesse o repositório duplistatus no GitHub.
  2. Vá até a seção "Releases" (ou clique em "Releases" na barra lateral direita).
  3. Clique em "Draft a new release".
  4. No campo "Choose a tag", digite o novo número da versão no formato vMAJOR.MINOR.PATCH (por exemplo, v1.2.0). Isso criará uma nova tag.
  5. Selecione master como branch de destino.
  6. Adicione um título do lançamento (por exemplo, "Release v1.2.0").
  7. Adicione uma descrição documentando as alterações nesta versão. Você pode:
    • Copiar o conteúdo de RELEASE_NOTES_github_VERSION.md (gerado por scripts/generate-readme-from-intro.sh)
    • Ou referenciar as notas de lançamento de documentation/docs/release-notes/ (mas observe que links relativos não funcionarão nos lançamentos do GitHub)
  8. Clique em "Publish release".

O que acontece automaticamente:

  • Uma nova tag Git é criada
  • O fluxo de trabalho "Build and Publish Docker Image" é acionado
  • Imagens Docker são construídas para as arquiteturas AMD64 e ARM64
  • As imagens são enviadas para:
    • Docker Hub: wsjbr/duplistatus:VERSION e wsjbr/duplistatus:latest (se for o lançamento mais recente)
    • GitHub Container Registry: ghcr.io/wsj-br/duplistatus:VERSION e ghcr.io/wsj-br/duplistatus:latest (se for o lançamento mais recente)

Método 2: Linha de Comando (Alternativa)​

Se você preferir usar a linha de comando, siga estas etapas:

Etapa 1: Atualizar Branch Master Local​

Certifique-se de que sua branch local master está atualizada:

# Checkout the master branch
git checkout master

# Pull the latest changes from the remote repository
git pull origin master

Etapa 2: Mesclar Ramificação de Desenvolvimento​

Mescle a branch vMAJOR.MINOR.x em master:

# Merge the vMAJOR.MINOR.x branch into master
git merge vMAJOR.MINOR.x

Se houver conflitos de mesclagem, resolva-os manualmente:

  1. Edite os arquivos em conflito
  2. Prepare os arquivos resolvidos: git add <file>
  3. Conclua a mesclagem: git commit

Etapa 3: Marcar a Versão​

Criar uma tag anotada para a nova versão:

# Create an annotated tag for the new version
git tag -a vMAJOR.MINOR.PATCH -m "Release vMAJOR.MINOR.PATCH - Brief description"

A flag -a cria uma tag anotada (recomendada para lançamentos), e a flag -m adiciona uma mensagem.

Etapa 4: Enviar para o GitHub​

Envie tanto a branch master atualizada quanto a nova tag:

# Push the updated master branch
git push origin master

# Push the new tag
git push origin vMAJOR.MINOR.PATCH

Alternativamente, envie todas as tags de uma vez: git push --tags

Etapa 5: Criar Versão do GitHub​

Após fazer push da tag, crie uma versão no GitHub (consulte o Método 1, Etapa 3) para disparar o fluxo de trabalho de compilação do Docker.

Construção Manual de Imagem Docker​

Para disparar manualmente o fluxo de trabalho de compilação da imagem Docker sem criar uma versão:

  1. Acesse o repositório duplistatus no GitHub.
  2. Clique na aba "Ações".
  3. Selecione o fluxo de trabalho "Build and Publish Docker Image".
  4. Clique em "Run workflow".
  5. Selecione a branch a partir da qual será feita a compilação (normalmente master).
  6. Clique novamente em "Run workflow".

Nota: Compilações manuais não marcarão automaticamente imagens como latest a menos que o fluxo de trabalho determine que seja a versão mais recente.

Lançando Documentação​

A documentação está hospedada em GitHub Pages e é implantada separadamente do lançamento da aplicação. Siga estas etapas para lançar a documentação atualizada:

Pré-requisitos​

  1. Certifique-se de que você tem um Token de Acesso Pessoal do GitHub com o escopo repo.
  2. Configure as credenciais do Git (configuração única):
cd documentation
./setup-git-credentials.sh

Isso solicitará seu Token de Acesso Pessoal do GitHub e o armazenará com segurança.

Documentação de Implantação​

  1. Navegue até o diretório documentation:
cd documentation

  1. Certifique-se de que todas as alterações de documentação sejam confirmadas e enviadas para o repositório.

  2. Construir e implantar a documentação:

pnpm run deploy

Este comando irá:

Quando Implantar Documentação​

Implante atualizações de documentação:

  • Após mesclar alterações de documentação para master
  • Ao lançar uma nova versão (se a documentação foi atualizada)
  • Após melhorias significativas na documentação

Nota: A implantação da documentação é independente das versões da aplicação. Você pode implantar a documentação várias vezes entre as versões da aplicação.

Preparando Notas de Lançamento para GitHub​

O script generate-readme-from-intro.sh gera automaticamente notas de lançamento do GitHub quando executado. Ele lê as notas de lançamento de documentation/docs/release-notes/VERSION.md (onde VERSION é extraído de package.json) e cria RELEASE_NOTES_github_VERSION.md na raiz do projeto.

Exemplo:

# This will generate README.md, README_dockerhub.md, and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

O arquivo de notas de lançamento gerado pode ser copiado e colado diretamente na descrição de lançamento do GitHub. Todos os links e imagens funcionarão corretamente no contexto de lançamento do GitHub.

Nota: O arquivo gerado é temporário e pode ser deletado após criar a versão no GitHub. É recomendado adicionar RELEASE_NOTES_github_*.md ao .gitignore se você não quiser fazer commit desses arquivos.

Atualizar README.md​

Se você fez alterações em documentation/docs/intro.md, regenere o README.md do repositório:

./scripts/generate-readme-from-intro.sh

Este script:

  • Extrai a versão de package.json
  • Gera README.md a partir de documentation/docs/intro.md (converte destaques do Docusaurus em alertas no estilo GitHub, converte links e imagens)
  • Cria README_dockerhub.md para o Docker Hub (com formatação compatível com o Docker Hub)
  • Gera RELEASE_NOTES_github_VERSION.md a partir de documentation/docs/release-notes/VERSION.md (converte links e imagens em URLs absolutas)
  • Atualiza o sumário usando doctoc

Faça commit e push do README.md atualizado junto com seu release.