openclaw-changelog-update

Atualização de Changelog OpenClaw

Use isso para reescritas de changelog e texto fonte de notas de lançamento do GitHub. Para beta/estável regular, 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 Lançamento. O trabalho editorial pode se sobrepor à validação do Código. Não execute novamente por backport de recuperação de validação; quando backports substituírem o SHA do Código, execute novamente uma vez após o SHA do Código final estiver verde, como um descendente genuíno apenas de CHANGELOG sob a política de reutilização de evidência de produto existente (timing). Para extended-stable, execute antes da validação e etiquetagem final exata do head. Não execute novamente para tentativas de ferramentas, retomada de publicação ou promoção. Use com release-openclaw-maintainer; esta skill possui o conteúdo do changelog, ordenação, agrupamento e disciplina de atribuição.

Objetivo

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

CHANGELOG.md é o índice de lançamento gerado. O proprietário compartilhado scripts/lib/release-changelog.mjs resolve seções de lançamento e registros de contribuição a partir de uma árvore de trabalho ou de uma ref Git fixada, incluindo refs históricas que ainda contêm um monólito. 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 de divisão ausente não deve recorrer ao índice raiz. Lançamentos 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 escritas 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 lançamento, correspondendo a CHANGELOG/records/<version>.md quando presente, e o índice juntos. A geração inicial retém o formato da seção abaixo. Os espelhos de documentos publicados seguem a rota pós-lançamento 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 de base beta: capture a versão atualmente selecionada pelo npm público openclaw@beta antes da publicação, não o último pré-lançamento do GitHub ou a versão mais alta com sufixo beta. O seletor pode nomear também uma versão estável 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 recente, a geração se recusa a adivinhar o estado histórico do seletor; forneça a tag capturada anteriormente. Quando essa tag não for um ancestral (por exemplo, um fechamento estável forward-port), o verificador usa sua base de merge alcançável e subtrai o registro de PR cumulativo 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 mais antigo do GitHub.
• Tag de base estável: última tag de lançamento 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 principal apenas quando 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 lançamento 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 principal canônica: origin/main atual, buscado antes da verificação. As notas de lançamento citam o PR principal original mesclado quando o mesmo trabalho é transportado por um backport. Um PR de branch de lançamento é usado apenas enquanto não houver forward-port no main atual.

Fluxo de Trabalho

1. Confirme o branch de lançamento 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 da Validação de Lançamento Completa e a tentativa quando a qualificação já existir
   • termine 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; retenha as exclusões de revert existentes.
   • também inspecione --since='24 hours ago' quando o main se moveu durante o lançamento.

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 Destaques, Mudanças e Correções usando o escritor compartilhado; gere o manifesto delta, então escreva prosa para esse intervalo apenas. Execuções subsequentes usam a tag de linha de base npm capturada explicitamente (não apenas o SHA da base de mesclagem de um intervalo divergente). Não consulte o npm novamente após a publicação ou sobrescreva a entrada estável cumulativa. Regere notas estáveis cumulativas na preparação estável.

   Adicione entradas repetíveis --release-provenance '<40sha> -> #PR[, #PR]' quando commits de lançamento não puderem transportar metadados de proveniência. Eles usam a mesma gramática de marcador exata e validação de fonte que os marcadores de corpo de commit. Um original de branch de lançamento mesclado é válido apenas enquanto não houver forward-port correspondente no main atual; seu commit de mesclagem do GitHub fixa a fonte original.

   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 lançamento 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 do Actions no mesmo repositório confirma o ID exato da execução. 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 relatadas como unavailableReferences no 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 de issue inline, 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 de leitor downstream suportado
   • 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 lançamento estável
   • relatórios de proveniência gerados separam PRs no intervalo de PRs apenas de seed retidos e, em seguida, declaram o total de linhas únicas. Um PR presente em ambos os inventários conta como no intervalo; nunca descreva o total inclusivo de seed como trabalho mesclado no intervalo de lançamento atual
   • adicione --shipped-ref <prior-shipped-tag> repetível quando o fechamento principal alcançável diferir da tag enviada ou commits de forward-port posteriores reassociarem PRs que já foram lançados. Cada tag é um limite enviado cumulativo: o verificador une linhas de PR explícitas de registros de contribuição completos em seções de lançamento numeradas, exclui apenas PRs sobrepostos, e ignora Unreleased. Nunca inferir esse limite a partir do SHA base, da prosa alvo ou do registro alvo. O manifesto e a proveniência gerada retêm cada tag mais o inventário e a contagem exatos de PRs excluídos 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 principal congelado para transportadores canônicos. Uma referência de fonte contextual torna-se uma contribuição apenas quando seu commit mesclado é alcançável no histórico alvo e seu tempo de mesclagem 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 lançamento continua. Seeds explícitos retêm sua associação histórica e permanecem apenas como seed, a menos que provados independentemente no intervalo. Resolva toda página de associação; existentes contratos canônicos, cherry-pick e proveniência 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írgulas com and final também funcionam). O final exato to restore the previous behavior. é aceito. Declarações duplicadas, abreviadas, incorporadas 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.
   • canonize backports para o PR mesclado original no main: origens explícitas de cherry-pick vencem, então uma correspondência de assunto normalizado única requer o mesmo autor e um caminho alterado sobreposto. Suprima PRs de lançamento/backport sempre que o PR principal correspondente existir no origin/main atual. Mantenha um PR de branch de lançamento apenas quando essa mudança chegou lá primeiro e não foi ainda forward-ported 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 de livro-razão público; 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 lançamento selecionada:

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

5. Forma da seção:

   • ### Highlights: 5-8 marcadores para estável, 0-8 para um delta beta; não invente destaques 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 entre superfícies, ou um marco de integração/compatibilidade que define o lançamento
     • cada destaque deve dizer o que mudou para um usuário em uma frase; use uma história de usuário por marcador 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 instalação/atualização material, segurança de dados, ou melhoria de usuário amplamente visível
   • ### Changes: novas capacidades e mudanças de comportamento
   • ### Fixes: correções voltadas ao usuário primeiro, agrupadas por impacto e superfície
   • agrupe mudanças/correções relacionadas por superfície e impacto no usuário; evite um marcador por commit minúsculo quando vários commits contam uma história voltada ao usuário
   • ### Complete contribution record: registro gerado primeiro de PR após a prosa agrupada; é a superfície de contabilidade exaustiva, não um segundo resumo de lançamento

6. Preserve atribuição verificada:

   • a autoria do PR vem do PR canônico do GitHub, nunca do autor do commit de lançamento, committer ou operador de backport. Resolva coautores a partir do commit de mesclagem original desse PR; trailers de transportador de lançamento 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. Seeds retêm associação e referências, não verificação antiga