Lançamentos

A Release o fluxo de trabalho começa quando um mantenedor empurra uma v* tag. Não existe nenhuma versão automática nos pushs de branch normais ou nos pedidos de pull.

Contrato de versão

Usar etiquetas canónicas como v0.1.0 ou v0.1.0-rc.1. A versão da aplicação e Docker versão tag omit the leading v. Componentes numéricos principais, espaço em branco, caracteres de shell e metadados de compilação SemVer (+...) são rejeitados antes da publicação. Identificadores numéricos de pré-lançamento também devem ser canônicos.

Cada lançamento inclui:

• sublane_VERSION_linux_amd64.tar.gz e sublane_VERSION_linux_arm64.tar.gz.
• docker.compose.yaml e SHA256SUMS para os ficheiros de lançamento público.
• Uma multiplataforma ghcr.io/murongg/sublane:VERSION imagem, mais as duas etiquetas de arquitetura.
• Mantenha as notas de lançamento do Changelog geradas a partir do histórico do Git com git-cliff fixo 2.14.2.

Somente a tag de versão estável mais alta atualmente presente no repositório pode atualizar o Docker latest canal e GitHubA designação de lançamento mais recente. Uma versão de pré- lançamento ou uma versão de manutenção mais antiga nunca move esses canais para trás. Se a compilação da etiqueta mais estável falhar, execute de novo essa versão; as etiquetas mais baixas não tomam o seu lugar intencionalmente. As implementações devem fixar uma versão ou digerir em vez de confiar em latest.

Configuração do repositório pela primeira vez

O fluxo de trabalho usa GITHUB_TOKEN, âmbito de aplicação contents: write e packages: write apenas no trabalho de publicação. Docker Conta Hub ou um token de acesso pessoal. GitHub As ações e a publicação do pacote GHCR devem ser permitidas pela política de repositório/organização. Todas as dependências de ação são fixadas para SHAs de commit completo.

A legenda de origem do repositório liga a imagem ao repositório. Os pacotes GHCR podem inicialmente ser privados, mesmo para um repositório de origem público. Após a primeira publicação bem- sucedida, verifique as configurações de acesso do pacote e torne- o público se forem feitas buscas anônimas. Veja GitHub's Documentação do registo de contentores. Mantenha pacotes publicados associados a este repositório para que fluxos de trabalho subsequentes retenham o acesso de escrita.

Publicar uma versão

Gerar e rever CHANGELOG.md no seu ramo de desenvolvimento com make changelog, em seguida, commit-lo com a documentação de versão. Mesclar essas alterações eo fluxo de trabalho de lançamento primeiro, e executar make check. Escolha uma nova versão não utilizada; não mova uma etiqueta de lançamento existente.

Por exemplo, depois de escolher v0.1.0:

git switch main
git pull --ff-only
make publish-check TAG=v0.1.0
make publish TAG=v0.1.0

make publish-check executa o mesmo pré-voo sem criar ou empurrar uma tag. make publish cria uma etiqueta anotada no commit inspecionado e empurra apenas essa tag. Ambos requerem uma árvore de trabalho limpa (incluindo arquivos não rastreados), o main branch, um workflow de lançamento existente nesse commit, e exatamente um origin empurrar o destino de quem main corresponde às tags locais HEAD. As duplicatas locais ou remotas são rejeitadas. Nenhuma ramificação é comutada, mesclada ou pressionada automaticamente.

A etiqueta determina o tipo de lançamento; não é necessária nenhuma bandeira de pré-lançamento separada:

make publish TAG=v0.1.0-rc.1

Você também pode correr node scripts/publish.mjs v0.1.0 --dry-run ou node scripts/publish.mjs v0.1.0 diretamente do repositório. Node.js 24 e Git são necessários, com as credenciais Git push trabalhando (por exemplo, um agente SSH); Docker As credenciais do Hub não são necessárias. O script verifica a etiqueta remota após carregar e imprimir o GitHub Ligação de fluxo de trabalho das acções quando o comando configurado utiliza um reconhecido GitHub URL.

Se um push falhar ou o seu resultado não puder ser verificado, a marca local é retida porque o comando já pode tê- lo aceite. Inspecione primeiro o comando remoto e as Ações. Se a marca remota estiver ausente, use o comando de repetição de uma marca impressa pelo programa. Ele nunca apaga as etiquetas ou os pushes de força. O script ativa o pipeline de CI existente; ele não reporta a compilação ou publicação como completa apenas porque o push de marca foi bem- sucedido.

A versão de exemplo é ilustrativa. Publique uma versão escolhida de cada vez e inspecione o resultado das Ações antes de anunciar a disponibilidade. Empurrar uma tag de versão é o gatilho da publicação; o fluxo de trabalho cria a GitHub Libertar-se a si próprio.

Sequência de fluxo de trabalho

1. Validar a etiqueta e calcular o caminho da imagem GHCR minúscula a partir do nome do repositório.
2. Chame o fluxo de trabalho normal do CI: verificação de deriva sqlc, teste de corrida / vet, verificação de frontend / build, testes de liberação de metadados e Compose validação.
3. Construir e fumar-teste o Docker imagem em corredores amd64 e arm64 nativos. Em RPs e versões, extraia o binário real de cada imagem testada, empacote-o com arquivos de implantação e avisos de licença, desempacote-o e execute-o para verificar a versão. As execuções de lançamento também salvam ambas as imagens testadas como artefatos de Ações de curta duração.
4. Depois de todas as verificações passar, obter o histórico completo marcado, gerar notas de lançamento com cliff.toml, e criar ou retomar um rascunho GitHub Release. As notas de rascunho são regeneradas em repetição; uma versão publicada anteriormente nunca é sobrescrita.
5. Carregar e empurrar as imagens testadas, então criar a tag de versão multi-plataforma. Nenhuma segunda compilação de aplicativos acontece durante a publicação.
6. Enviar os arquivos binários, Compose e checksums SHA-256. Promova o mais novo canal estável quando elegível e, em seguida, publique o lançamento concluído.

As etiquetas de versão/fonte/revisão estão incorporadas na imagem e sublane --version relata a versão empacotada. Os sistemas de arquivos raiz de imagem contêm apenas utilitários de tempo de execução alpinos, certificados públicos de CA, os avisos binários e de licença. Nenhuma verificação de código-fonte, compilador, dependências de Node.js ou dados locais está incluída. Construir contexto allowlisting exclui bases de dados locais, chaves de criptografia, backups e árvores de trabalho.

Falhas e repetições

Utilização Repetir as tarefas falhadas no fluxo de trabalho da mesma tag roda quando uma operação de rede, compilação ou registro falha. Antes da conclusão, os artefatos de liberação permanecem em um rascunho e podem ser substituídos por uma re- tentativa. As imagens por arquitetura/versão podem já existir se um passo posterior falhar; o re- tentativa completa a mesma versão. Publicando o registro e GitHub A liberação não pode ser uma transação atômica, então verifique ambos os destinos após uma falha.

Os artefatos são retidos por sete dias. Após o término, reexecute todas as tarefas para reconstruí- los e re- testá- los. Reexecuções substituem artefatos de Ações com o mesmo nome dentro dessa execução; já publicado GitHub Os lançamentos permanecem protegidos. Uma vez que uma versão seja publicada, use uma nova versão para correções de código ou embalagem em vez de sobrescrevê- lo. Excluir ou mover uma tag não retorna os binários baixados, imagens publicadas ou bancos de dados implantados.

GITHUB_TOKEN- created tag pushes normalmente não desencadeia outro fluxo de trabalho. Se outra automação criar tags, use um escopo apropriado GitHub Aplique/toque ou ative a liberação através de um fluxo de despacho explicitamente projetado. Mantenedor manual empurra o trabalho sem essa configuração extra. Veja GitHub's regras de desencadeamento do fluxo de trabalho.

Acondicionamento local

make release VERSION=0.0.0-test

Isto constrói o frontend uma vez, combina os dois binários Linux e escreve arquivos mais SHA256SUMS sob ignorado dist/release/. Os arquivos existentes não são sobrescritos; use uma versão de teste nova ou mova artefatos gerados anteriormente antes de reconstruir. Este comando não empurra imagens ou cria lançamentos. Mantenha a validação de compilação local separada da evidência de tempo de execução de container nativo.

Geração do Changelog

Instalar git-cliff 2.14.2 (a versão fixada em CI). É uma ferramenta de desenvolvimento, não uma dependência do servidor. Por exemplo, com o Rust instalado, use cargo install git-cliff --locked --version 2.14.2. Um executável baixado pode ser selecionado através GIT_CLIFF=/path/to/git-cliff.

make changelog
make changelog-check

cliff.toml usa Manter um cabeçalho do Changelog: Adicionado, Modificado, Desprecado, Removido, Fixo e Segurança. Funcionalidades e correções seguem os Commits Convencionais; as construções, o desempenho e os refatores são alterados. As deprecações/removimentos explícitos e as alterações de segurança são obtidas por suas próprias seções. Documentos, testes, estilo e tarefas rotineiros são omitidos, enquanto quebram as mudanças e suas explicações permanecem visíveis. Mesclar mensagens e commits não convencionais são excluídos; reveja o texto gerado antes de ser lançado.

A geração lê o histórico do Git local com metadados de rede e comandos de modelos externos desactivados. Substitui CHANGELOG.md só depois de renderizar sucesso, e não criar tags, alterar versões ou commit arquivos. Persistir o arquivo gerado através do fluxo de PR normal antes de executar make publish, que ainda requer um main sincronizado limpo. Os changelogs do repositório incluem seções de pré-lançamento; notas de lançamento estáveis resumem todo o ciclo desde a tag estável anterior, incluindo alterações introduzidas pela primeira vez em pré-lançamentos.

Para uma etiqueta existente verificada no HEAD:

make release-notes TAG=v0.1.0

Isto escreve dist/release-notes.md usando o mesmo modelo; o fluxo de trabalho de lançamento instala o gerador pinado, obtém o histórico completo e passa este arquivo para GitHub. Uma tag em falta ou não compatível é rejeitada. O CI executa testes de integração de história sintética; execute make changelog-check localmente para habilitar esses testes quando git-cliff estiver instalado. Ordinary make check mantém-nas opcionais, a menos que SUBLANE_TEST_CHANGELOG=1 Nenhum dos comandos altera o README.