openclaw-changelog-update

OpenClaw Changelog Update

Use esta skill para reescritas de changelog e texto fonte de notas de release no GitHub. Para releases beta/estável regulares, prepare notas completas antes da qualificação da fonte final quando possível; o SHA do código pode então também ser o SHA do release. O trabalho editorial pode sobrepor a validação do código. Não a execute novamente por backport de recuperação de validação; quando backports substituem o SHA do código, execute-a uma vez após o SHA do código final estar verde, como um descendente genuíno apenas de CHANGELOG sob a política existente de reuso de evidência de produto (timing). Para releases extended-stable, execute-a antes da validação e etiquetagem final exata do head. Não a execute novamente para repetições de ferramentas, publicação retomada ou promoção. Use-a com release-openclaw-maintainer; esta skill possui o conteúdo do changelog, ordenação, agrupamento e disciplina de atribuição.

Objetivo

Reconstrua a seção de release alvo CHANGELOG/<version>.md a partir de um manifesto de histórico completo e gerado, não de notas de rascunho desatualizadas. Produza notas de release voltadas ao usuário agrupadas ordenadas por interesse do usuário, preservando toda referência de issue/PR relevante e toda atribuição humana verificada Thanks @....

CHANGELOG.md é o índice de release gerado. O proprietário compartilhado scripts/lib/release-changelog.mjs resolve seções de release e registros de contribuição a partir de uma árvore de trabalho ou de um ref Git fixo, incluindo refs históricos que ainda contêm um monolito. Use node scripts/release-changelog.mjs read --version <version> [--ref <sha-or-tag>] para uma seção, ou adicione --record para seu registro de contribuição. Um artefato dividido ausente não deve recorrer ao índice raiz. Releases históricos sem registros não ganham proveniência inventada. Arquivos CHANGELOG/** gerados retêm bytes exatos migrados ou espelhados e são excluídos da formatação genérica, como o changelog raiz. Valide-os através de seu proprietário com pnpm changelog:check.

As gravações atuais usam o layout dividido. Para salvar uma seção inicial completa, use node scripts/release-changelog.mjs write --version <version> --file <section.md>; isso atualiza a entrada de release, combinando CHANGELOG/records/<version>.md quando presente, e o índice juntos. A geração inicial mantém o formato da seção abaixo. Os espelhos de docs publicados seguem a rota pós-release separada no final desta skill; a geração inicial nunca deve sobrescrevê-los.

Entradas

• Versão alvo: YYYY.M.PATCH-beta.N exata para um delta beta; YYYY.M.PATCH para notas estáveis cumulativas. Entradas e registros beta são artefatos congelados separados, nunca cópias da seção de base estável.
• Tag base beta: capture a versão atualmente selecionada pelo npm público openclaw@beta antes da publicação, não a última pré-release do GitHub ou a versão mais alta com sufixo beta. O seletor pode nomear uma versão estável também selecionada por latest. Omita --base (ou use --base npm-beta) com uma versão beta exata para resolvê-la uma vez; preserve a tag resolvida do manifesto gerado e reutilize esse --base explícito para edições, verificação e recuperação. Se o npm já selecionar o candidato ou uma versão mais nova, a geração se recusa a adivinhar o estado histórico do seletor; forneça a tag previamente capturada. Quando essa tag não é um ancestral (por exemplo, um forward-port de fechamento estável), o verificador usa sua base de merge alcançável e subtrai o registro cumulativo de PR da tag enviada capturada através da semântica --shipped-ref. O manifesto e o registro retêm ambos os limites; repita com a tag capturada para resolver o mesmo intervalo, nunca selecione um beta GitHub mais antigo.
• Tag base estável: última tag de release estável enviada alcançável. Ela deve ser um ancestral do alvo; uma tag mais nova, mas divergente, não é um limite de histórico válido. Use um SHA explícito de envio/fechamento main apenas quando ele também for alcançável a partir do alvo.
• Ref alvo: o histórico exato de conclusão do produto sendo documentado. Seu alvo de registro de contribuição deve ser um ancestral do alvo de release final; ele não precisa nomear um commit de changelog ainda não criado. Inclua quaisquer correções posteriores antes de finalizar as notas. As notas finais podem ser commitadas antes da qualificação, ou depois como um descendente apenas de CHANGELOG de um SHA de código verde.
• Ref main canônica: origin/main atual, buscada antes da verificação. As notas de release citam o PR main original mesclado quando o mesmo trabalho é carregado por um backport. Um PR de branch de release é usado apenas enquanto nenhum forward-port existe no main atual.

Fluxo de Trabalho

1. Confirme a branch de release e o alvo de histórico exato:

   • git fetch --tags origin
   • confirme git status -sb limpo
   • registre git rev-parse HEAD como o alvo de histórico
   • registre o ID da execução de Full Release Validation e a tentativa quando a qualificação já existir
   • finalize as alterações pendentes de produto/versão/backport antes de congelar a fonte final; atualize o inventário para alterações reais

2. Audite o histórico, incluindo commits diretos:

   • git log --topo-order --date=iso-strict --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>
   • git log --topo-order --grep='(#' --date=short --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>
   • Inclua todo commit alcançável a partir do alvo, mas não da base, incluindo branches laterais mescladas. Resolva associações de PR antes de deduplicar e subtrair registros enviados; mantenha as exclusões de revert existentes.
   • também inspecione --since='24 hours ago' quando o main se moveu durante o release.

3. Gere o registro de contribuição completo e o manifesto editorial antes de escrever prosa agrupada:

   node --import tsx .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
     --base <base-tag> \
     --target <target-ref> \
     --release-branch <canonical-release-branch> \
     --main-ref origin/main \
     --version <YYYY.M.PATCH> \
     --manifest /tmp/openclaw-release-<YYYY.M.PATCH>.json \
     --write-ledger
   

   Para geração beta, use --version YYYY.M.PATCH-beta.N e omita --base na primeira execução de inventário. Inicie uma seção de versão exata com Highlights, Changes e Fixes usando o escritor compartilhado; gere o manifesto delta, então escreva prosa apenas para esse intervalo. Execuções subsequentes usam a tag de linha de base npm capturada explicitamente (não apenas o SHA da base de merge de um intervalo divergente). Não consulte npm novamente após a publicação ou sobrescreva a entrada estável cumulativa. Regere as notas estáveis cumulativas na preparação estável.

   Adicione entradas --release-provenance '<40sha> -> #PR[, #PR]' repetíveis quando commits de release não podem carregar metadados de proveniência. Elas usam a mesma gramática de marcador exata e validação de main atual que os marcadores de corpo de commit.

   O verificador reutiliza automaticamente respostas públicas do GraphQL do GitHub a partir de um snapshot exato de SHA base/alvo sob os metadados git da árvore de trabalho. Reescritas iterativas no mesmo alvo evitam descoberta de rede repetida. Use --refresh-github-snapshot após dados de API suspeitos, --github-snapshot <path> para um artefato explícito, ou --no-github-snapshot para uma auditoria apenas ao vivo. Os corpos de release do GitHub são sempre lidos ao vivo. Referências explícitas CI #, CI run #, Actions run #, e workflow run # na fonte ativa são classificadas separadamente apenas quando a resolução de issue/PR falha e uma consulta ao vivo de Actions do mesmo repositório confirma o ID de execução exato. Qualquer ocorrência comum desse número na fonte ativa, notas ou no registro de contribuição permanece um requisito estrito de issue/PR. Execuções confirmadas aparecem como workflowRuns na saída de verificação e no manifesto, nunca como associações de PR ou crédito de contribuidor. Apenas referências NOT_FOUND do GitHub confinadas ao texto contextual do corpo do commit, ausentes de assuntos, referências de fechamento, proveniência e notas/registros, e abaixo do número resolvido mais alto podem ser omitidas e reportadas como unavailableReferences do manifesto sem crédito.

   • o manifesto é a entrada necessária para a reescrita, não uma auditoria posterior; ele contém todo PR referenciado, crédito de contribuidor elegível, contexto inline de issue, todo commit direto, e uma classificação de elegibilidade editorial para PRs e commits diretos
   • a versão 3 do esquema é o contrato de manifesto efêmero necessário. Regere manifestos mais antigos; a versão 2 não é um limite suportado de leitor downstream
   • para um backfill histórico, adicione --seed-ref <pre-backfill-ref> uma vez para que registros de contribuição do changelog anterior sejam retidos mesmo quando um commit mesclado mais antigo omitiu seu número de PR; o verificador exclui registros para trabalho revertido após a tag base, incluindo trabalho beta revertido antes do release estável
   • a proveniência gerada relata PRs no intervalo separadamente de PRs retidos apenas de semente, depois declara o total único de linhas. Um PR presente em ambos os inventários conta como no intervalo; nunca descreva o total inclusivo de semente como trabalho mesclado no intervalo de release atual
   • adicione --shipped-ref <prior-shipped-tag> repetível quando o fechamento main alcançável difere da tag enviada ou commits de forward-port posteriores re-associam PRs que já foram lançados. Cada tag é um limite enviado cumulativo: o verificador une linhas explícitas de PR de registros de contribuição completos em seções de release numeradas, exclui apenas PRs sobrepostos, e ignora Unreleased. Nunca infira este limite do SHA base, prosa alvo ou registro alvo. O manifesto e a proveniência gerada retêm cada tag mais o inventário exato de PR excluído e contagem para validação determinística de candidatos
   • a descoberta de PR fonte limita as associações de commit do GitHub ao histórico alvo selecionado, ou ao histórico main congelado para carriers canônicos. Uma referência fonte contextual torna-se uma contribuição apenas quando seu commit mesclado é alcançável no histórico alvo e seu tempo de merge está dentro do alvo. Mantenha todas as referências resolvíveis, mas não promova PRs não relacionados meramente porque eles mesclam enquanto a preparação do release continua. Sementes explícitas retêm sua associação histórica e permanecem apenas semente a menos que provadas independentemente como no intervalo. Resolva toda página de associação; contratos canônicos, cherry-pick e de proveniência existentes permanecem autoritativos.
   • reverts explícitos de múltiplos commits requerem um assunto de revert e uma declaração independente Reverts <full SHA> and <full SHA>. (listas separadas por vírgula com and final também funcionam). O final exato to restore the previous behavior. é aceito. Declarações duplicadas, abreviadas, embutidas ou repetidas não estabelecem reversão. Cada commit nomeado deve ser um ancestral de pai único, e a aplicação reversa de todos os patches nomeados deve reproduzir a árvore de revert completa. Declarações reconhecidas que falham nesta prova param a verificação. Prova usa armazenamento privado de índice/objeto git sem hooks ou diffs externos; a contabilidade canônica de revert único e revert-de-revert permanece intacta.
   • canonicalize backports para o PR mesclado original em main: origens explícitas de cherry-pick vencem, então uma correspondência única de assunto normalizado requer o mesmo autor e um caminho alterado sobreposto. Suprima PRs de release/backport sempre que o PR main correspondente existir no origin/main atual. Mantenha um PR de branch de release apenas quando essa mudança chegou lá primeiro e ainda não foi forward-portada para main
   • leia o manifesto antes de editar ### Highlights, ### Changes, ou ### Fixes; não carregue prosa agrupada antiga sem reauditá-la
   • inspecione PRs/issues vinculados ou diffs para commits ambíguos. Commits diretos são entrada editorial, não linhas públicas de livro-razão; infira resultados materiais do usuário a partir do assunto, corpo, arquivos tocados, testes e commits próximos

4. Reescreva apenas uma seção de release selecionada:

   • beta: ## YYYY.M.PATCH-beta.N, contendo apenas mudanças desde a linha de base npm beta capturada
   • estável: ## YYYY.M.PATCH, cumulativa desde a linha de base estável anterior
   • não deixe uma seção ## Unreleased desatualizada acima do release alvo
   • se Unreleased contiver notas vinculadas ao release, incorpore-as na seção alvo em vez de deletá-las

5. Forma da seção:

   • ### Highlights: 5-8 bullets para estável, 0-8 para um delta beta; não invente highlights para pequenos hotfix betas
     • inclua apenas uma capacidade clara visível ao usuário ou desbloqueio de fluxo de trabalho, uma correção material de confiabilidade/segurança, uma melhoria ampla de superfície, ou um marco de integração/compatibilidade que define o release
     • cada highlight deve dizer o que mudou para um usuário em uma frase; use uma história de usuário por bullet e agrupe seus PRs de suporte
     • exclua testes, CI, refatorações, docs, rotatividade de catálogo e detalhes de implementação a menos que o resultado seja uma melhoria material de instalação/atualização, segurança de dados, ou melhoria amplamente visível ao usuário
   • ### Changes: novas capacidades e mudanças de comportamento
   • ### Fixes: correções voltadas ao usuário primeiro, agrupadas por impacto e superfície
   • agrupe changes/fixes relacionados por superfície e impacto do usuário; evite um bullet por commit minúsculo quando vários commits contam uma história voltada ao usuário
   • ### Complete contribution record: registro gerado primeiro por PR após a prosa agrupada; é a superfície de contabilidade exaustiva, não um segundo resumo de release

6. Preserve atribuição verificada:

   • a autoria do PR vem do PR canônico do GitHub, nunca do autor do commit de release, committer ou operador de backport. Resolva coautores a partir do commit de merge original desse PR; trailers de carrier de release e menções contextuais não estabelecem crédito em outro PR
   • reconstrua agradecimentos gerados a partir de evidências de PR, coautor original e repórter vinculado. Sementes retêm associação e referências, não agradecimentos antigos não verificados. Regeneração substitui crédito gerado desatualizado em registros e prosa agrupada; a verificação rejeita crédito ausente e não suportado

...