Publicar versões

Transforma uma compilação testada numa versão. Esta página é para mantenedores.

Cuidado

Só o mantenedor inicia uma versão. Não faças tags, não publiques nem movas uma etiqueta de imagem por tua conta.

Antes de começares

• Todas as verificações de Testes passam, incluindo uma execução completa de ponta a ponta e as execuções longas e de falhas.
• O CHANGELOG.md tem a versão nova.
• O Python 3 está instalado para os scripts de versão.

Prepara uma versão

1. Escreve releases/notes-<version>.toml, por exemplo releases/notes-1.0.0.toml. Vê o Ficheiro de notas da versão.

2. Verifica-o:

   python deploy/release/notes.py 1.0.0 --check

   Não deves ver erros. Uma palavra proibida, um travessão longo, uma data, conversa de lançamento ou um destaque repetido faz sair com código 1.

3. Gera os textos da versão:

   python deploy/release/notes.py 1.0.0

   Deves encontrar 7 ficheiros em releases/out/1.0.0/.

4. Compila a imagem e arranca-a com uma pasta de configuração nova:

   docker build --file deploy/Dockerfile .

   Deves ver o assistente da primeira execução.

5. Executa todas as verificações de Testes no teu computador. Os testes correm localmente, não no GitHub.

6. Entrega a versão ao mantenedor. O mantenedor envia a tag da versão para a main, e isso inicia a versão.

Opções

Nomes de versão e de tag

Coisa	Nome
Tag do Git (enviada pelo mantenedor)	1.0.0 (só números, sem v)
Etiqueta da imagem e version das notas	1.0.0

O workflow só arranca com uma tag X.Y.Z e pára quando a tag é diferente do ficheiro VERSION.

Etiquetas da imagem

Cada versão envia a sua etiqueta de versão e :latest.

Retira uma versão

1. Envia a versão seguinte com a correção.
2. Marca a versão má na lista de atualizações para que as instalações não a ofereçam.
3. Mantém a tag.

Se não funcionar

Sintoma. notes.py --check sai com código 1. Causa. O ficheiro de notas quebra uma regra. A mensagem indica a linha. Solução. Edita o ficheiro de notas, nunca os ficheiros em releases/out, e executa outra vez.

Sintoma. O workflow pára com VERSION says. Causa. A tag e o ficheiro VERSION são diferentes. Solução. Corrige o VERSION na main e envia a tag da versão seguinte.

Para especialistas

Ficheiro de notas da versão

Todos os textos da versão saem de um só ficheiro. Nunca edites à mão o que ele gera.

Campo	Conteúdo
version	X.Y.Z simples
theme	Uma linha
images	Lista de {registry, name}. Só o Docker Hub holyarrs/holyarrs
docs_url	Opcional. Vazio significa sem ligação para a documentação
[[highlights]]	Exatamente 3, cada um com line, issues e shot. Os issues deles não aparecem em nenhuma linha de grupo
[groups]	Linhas por sítio. New é o predefinido. As outras começam por Changed: , Fixed: ou Docs: . Cada uma termina com o seu issue, como (#46). Um sítio com menos de 3 linhas vai para Also new
Opcional	[before_you_update] (breaking, manual_steps, backup, rollback), security, known_issues, credits, [stats]. As partes vazias ficam escondidas

Usa um nome de utilizador do GitHub só quando for conhecido, no ficheiro de notas ou em releases/credits-map.json.

Ordem do corpo: tema, Highlights, sítios (Requests, Library, Downloads, Indexers, Accounts, Health, Setup, Install), Also new, Security, Known issues, Before you update, Image, Thanks, linha de estatísticas.

Saída em releases/out/<version>/	Serve para
changelog.md	A entrada do changelog
github.md	O corpo da versão no GitHub
update-notes.json	As notas que a app mostra
reddit.txt	A publicação no Reddit
discord-dm.txt, discord-announce.md	Discord. Cada um fica abaixo de 1000 carateres
roadmap-card.json	O cartão do roadmap

O notes.py aceita --file (outro ficheiro de notas), --map (outro mapa de créditos), --out (outra pasta de saída) e --date. O --check avisa de linhas longas e de quase repetições.

O workflow da imagem

O workflow HolyArrs - Release arranca quando uma tag de versão é enviada. Tem três passos:

1. Compilar e enviar a imagem para linux/amd64, linux/arm64 e linux/arm/v7, com a etiqueta da versão e latest.
2. Atualizar a descrição do Docker Hub a partir do README.md.
3. Publicar a versão no GitHub com a secção desta versão do CHANGELOG.md.

Lista de atualizações

A app lê uma lista de atualizações assinada. Cada versão acrescenta a sua entrada e assina-a. A chave de assinatura nunca vai para o repositório. O HolyArrs recusa uma lista que não consiga verificar.

Depois de uma versão, confirma que a label de versão da imagem coincide com a tag e vigia os issues novos durante o primeiro dia:

docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' holyarrs

Modelo de teste para Unraid

O deploy/release/nas-template.py escreve um modelo de utilizador do Unraid para uma imagem exata. Não puxa, não instala nem publica nada.

python deploy/release/nas-template.py --image 'holyarrs/holyarrs@sha256:<digest>' --config '/mnt/<pool>/appdata/holyarrs-test' --movies /mnt/user/holyarrs-test-data/movies --downloads /mnt/user/holyarrs-test-data/downloads --port 6262 --output holyarrs-test.xml

Substitui <digest> e <pool>.

Opção	Notas
--image	O digest do manifesto do registo, não um ID de imagem Docker
--config	Um caminho de pool. A ferramenta recusa /mnt/user e /mnt/user0
--movies, --tv, --music, --downloads	Opcionais. Caminhos separados são montagens separadas, por isso as importações copiam
--port	Por predefinição é 6262
--allowed-hosts	Opcional, nomes de anfitrião separados por vírgulas
--output	O ficheiro XML a escrever

O modelo define PUID=99, PGID=100 e UMASK=022. Dá a essa conta permissão de escrita nos ficheiros multimédia de teste. Põe o ficheiro em /boot/config/plugins/dockerMan/templates-user/ e escolhe-o em Docker > Add Container > Template (Docker > Adicionar contentor > Modelo).

Relacionado

• Testes
• Contribuir
• Atualizações