Release Workflow (UI components)

Descreve o fluxo obrigatório para publicar uma release de qualquer componente com UI (desktop, mobile, web, TV) no monorepo Koder/koder.

Fluxo padrão

git tag <area>/<componente>/v<versão>
git push origin <area>/<componente>/v<versão>

Isso é tudo. O Koder Flow dispara o pipeline automaticamente:

1. Detecta quais plataformas o componente tem implementadas (lê o filesystem)
2. Builda cada plataforma disponível
3. Cria a release no Flow com todos os artefatos
4. Publica os artefatos na Koder Hub

Exemplo:

git tag products/horizontal/kmail/v1.0.4
git push origin products/horizontal/kmail/v1.0.4

Convenção de tag

Padrão geral: <área>/<componente>/v<semver>.

A versão em koder.toml e pubspec.yaml deve estar atualizada antes de criar a tag.

Plataformas construídas automaticamente

O pipeline detecta plataformas pelo filesystem — nenhuma configuração explícita necessária:

macOS e iOS são detectados mas sempre pulados — requerem runner macOS com certs.

Se uma plataforma não estiver implementada (diretório ausente), o pipeline a ignora sem falhar.

Adicionar um novo componente ao pipeline

1. Criar o componente com flutter create ou scaffold manual no path <área>/<componente>/app/
2. Adicionar koder.toml mínimo no diretório do app:

   [app]
   slug    = "koder-<componente>"
   name    = "Koder <Componente>"
   version = "1.0.0"

3. Gerar o workflow de release:

   # Adicionar o componente na lista COMPONENTS em .gitea/scripts/gen-release-workflows.py
   # Re-executar:
   python3 .gitea/scripts/gen-release-workflows.py

4. Commitar e fazer push do novo workflow.
5. Para ativar o build Windows: registrar o secret WINRM_PASS no Gitea (ver abaixo).

Renomear um componente no pipeline

1. Renomear o diretório no monorepo: git mv <área>/<nome-antigo> <área>/<nome-novo>
2. Localizar a entrada antiga na lista COMPONENTS em .gitea/scripts/gen-release-workflows.py

   e atualizar todos os campos: workflow_name, area, tag_prefix, app_path, slug, display_name.

3. Regenerar os workflows:

   python3 .gitea/scripts/gen-release-workflows.py

4. Deletar o arquivo de workflow do nome antigo:

   rm .gitea/workflows/<nome-antigo>-release.yml

5. Atualizar koder.toml do componente: campos slug e name.
6. Commitar e fazer push — inclua o diretório renomeado, os workflows atualizados e o koder.toml.

Arquivar um componente no pipeline

1. Remover a entrada do componente da lista COMPONENTS em gen-release-workflows.py.
2. Deletar o arquivo de workflow órfão:

   rm .gitea/workflows/<nome>-release.yml

3. Commitar e fazer push.

O diretório do componente pode ser mantido no monorepo (histórico) ou arquivado num branch separado — a remoção do workflow é o que desativa o pipeline.

Secrets necessários no Koder Flow

Registrar em Settings → Secrets do repo Koder/koder:

Se WINRM_PASS não estiver configurado, o build Windows é pulado com aviso — o restante das plataformas é publicado normalmente.

Documentação e landing page após release

Toda release deve atualizar a documentação do componente e verificar a landing page:

1. Documentação do Stack — executar /k-housekeep <área>/<componente> após a release. O comando atualiza o deep-dive em docs/stack/modules/ com a nova versão/status e regenera os PDFs.
2. Paridade de conteúdo — o k-housekeep verifica automaticamente se o hero, features list, version badges e textos de download da landing page estão consistentes com o koder.toml e CHANGELOG.md atualizados.
3. Não pular — releases sem esse passo fazem a documentação e a landing page divergirem silenciosamente do componente real.

Se o componente não tiver deep-dive ainda, o /k-housekeep <área>/<componente> o cria automaticamente.

Atualizar a versão antes de taggear

Flutter (pubspec.yaml):

version: 1.0.4+5   # semver+build_number

koder.toml:

[app]
version = "1.0.4"

Ambos devem estar commitados antes de criar a tag.

Referências técnicas

• Implementação do pipeline: .gitea/README.md
• Formatos de pacote aceitos: meta/docs/stack/specs/releases/packaging.kmd
• Build Windows via WinRM: meta/docs/stack/policies/windows-builds.kmd

Hub apt como canal canônico de install (.deb)

A partir de distro#012 (2026-05-20), os pacotes .deb da koder-suite são instalados no Koder Kodix via apt-get install contra https://hub.koder.dev/apt stable main. Os tags de release no Flow continuam sendo o source-of-truth dos .debs (a CI publica do Flow release pro Hub apt), mas o consumo acontece via Hub apt:

• Hook 0060-koder-suite.hook.chroot em `infralinuxkodixvariants

  {desktop,server}hookslive/ faz apt-get install -y dos pacotes listados em koder-suite-packages.txt`.

• Hub apt serve Release + InRelease (clearsigned com a chave v1

  375BC2537CEE0D8E919DA8D1073EDD7DCCA54EB9) + Packages (gz+xz) + pool/main/<initial>/<slug>/<file>.deb per hub-RFC-007 §6.1.

• Mapeamento (slug × .deb Package × Flow tag × arch) em

  meta/docs/stack/registries/koder-suite-deb-mapping.md.

• Bulk-import inicial dos 12 .debs foi feito em hub#139 (2026-05-20);

  releases futuras devem disparar khub publish automaticamente (hub#103 long-term Gitea Action — atualmente manual, script-base preservado em hub#139 closure notes).

Componentes que ainda precisam shipar .deb para Hub:

• Desktop: 12/13 já publicados; só falta koder umbrella (distro#017

  — pending first release tag).

• Server: 0/6 publicados (koder-id-daemon, koder-reporter,

  koder-certs, koder-billing, koder-jet, koder-kdb-next — cada componente flipa pra required no variants/server/koder-suite-packages.txt quando shipa seu .deb).