Pular para o conteúdo principal

Gerenciamento de Versões

Versionamento (Versionamento Semântico)​

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

  • MAJOR (x.0.0): Quando você faz alterações de API incompatíveis
  • MINOR (0.x.0): Quando você adiciona funcionalidade de forma compatível com versões anteriores
  • PATCH (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 ter concluído 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 em todos os arquivos).
  • Todos os testes passam (em modo devel, 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 versões do SQLite apenas pela versão principal (por exemplo, 3.45.1 vs 3.51.1 são consideradas compatíveis) e compara as versões de Node, npm e Duplistatus exatamente.
  • 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 Solicitações de Pull e Lançamentos do GitHub (veja abaixo). Isso fornece 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 Solicitação de Pull​

  1. Navegue até o repositório duplistatus no GitHub.
  2. Clique na aba "Pull requests".
  3. Clique em "New pull request".
  4. Defina o branch base para master e o branch de comparação para vMAJOR.MINOR.x.
  5. Revise a visualização 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 em "Create pull request" novamente.

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

Após revisar a solicitação de pull:

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

Etapa 3: Criar Lançamento do GitHub​

Após a mesclagem ser concluída, crie um lançamento do GitHub:

  1. Navegue até o repositório duplistatus no GitHub.
  2. Vá para 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 seu novo número de versão no formato vMAJOR.MINOR.PATCH (por exemplo, v1.2.0). Isso criará uma nova tag.
  5. Selecione master como o branch de destino.
  6. Adicione um título de versão (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 versão de documentation/docs/release-notes/ (mas observe que links relativos não funcionarão nas versões do GitHub)
  8. Clique em "Publicar versão."

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 arquiteturas AMD64 e ARM64
  • As imagens são enviadas para:
    • Docker Hub: wsjbr/duplistatus:VERSION e wsjbr/duplistatus:latest (se este for o lançamento mais recente)
    • GitHub Container Registry: ghcr.io/wsj-br/duplistatus:VERSION e ghcr.io/wsj-br/duplistatus:latest (se este for o lançamento mais recente)

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

A partir do commit que deve ser lançado (normalmente master, já enviado via push), com uma árvore de trabalho limpa e documentation/docs/release-notes/VERSION.md no devido lugar:

pnpm release:github:dry   # print the planned tag, notes file, and gh command
pnpm release:github       # generate GitHub notes, tag vVERSION at HEAD, publish the release, and deploy the docs

O scripts/release.mjs lê a versão de package.json, executa scripts/generate-readme-from-intro.sh (para que RELEASE_NOTES_github_VERSION.md tenha links absolutos) e cria a release do GitHub. A sua publicação inicia o fluxo de trabalho da imagem Docker. Em seguida, o script executa pnpm run deploy em documentation/ para compilar o site Docusaurus e enviá-lo via push para gh-pages. Se a tag vVERSION ou essa release do GitHub já existir, o script as excluirá e recriará a tag no HEAD atual. Passe --verify-clean=false para ignorar as verificações de árvore limpa.

As etapas abaixo são as mesmas operações executadas manualmente.

Etapa 1: Atualizar Ramo Master Local​

Certifique-se de que seu ramo master local está atualizado:

# Checkout the master branch
git checkout master

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

Etapa 2: Mesclar Ramo de Desenvolvimento​

Mescle o ramo 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 o Lançamento​

Crie 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"

O sinalizador -a cria uma tag anotada (recomendada para lançamentos), e o sinalizador -m adiciona uma mensagem.

Etapa 4: Enviar para GitHub​

Envie tanto o ramo master atualizado 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 Lançamento no GitHub​

Após enviar a tag, crie um lançamento no GitHub (veja Método 1, Etapa 3) para acionar o fluxo de trabalho de construção do Docker.

Compilação Manual da Imagem Docker​

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

  1. Navegue até 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 o branch para compilar (normalmente master).
  6. Clique em "Run workflow" novamente.

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

Lançamento da Documentação​

A documentação é hospedada no GitHub Pages. O pnpm release:github faz a implantação dela após a publicação da release do GitHub. Para atualizar o site entre as versões da aplicação, siga estas etapas:

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.

Implantar Documentação​

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

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

  2. Compile e implante 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 dos lançamentos da aplicação. Você pode implantar a documentação várias vezes entre lançamentos 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 a .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 repositório README.md:

./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 admonições do Docusaurus para alertas no estilo GitHub, converte links e imagens)
  • Cria README_dockerhub.md para Docker Hub (com formatação compatível com Docker Hub)
  • Gera RELEASE_NOTES_github_VERSION.md a partir de documentation/docs/release-notes/VERSION.md (converte links e imagens para URLs absolutas)
  • Atualiza o índice de conteúdo usando doctoc

Faça commit e envie o README.md atualizado junto com sua versão.