AkiGarage/readme-release-sync

Sincronização de README e Release

Use esta habilidade sempre que uma tarefa envolver cópia do README, notas de release, changelogs, capturas de tela/GIFs do produto ou documentação bilíngue do produto.

O objetivo é reduzir a carga de revisão do mantenedor: a documentação deve corresponder ao estado real do produto antes que os revisores precisem detectar nomes desatualizados, capturas de tela, descrições de funcionalidades ou inconsistências entre inglês e japonês.

Regra Principal

Não edite documentos voltados ao produto baseando-se apenas nos documentos existentes. Primeiro, identifique a fonte oficial de verdade atual: código do aplicativo, strings de UI, capturas de tela/GIFs, branch de release, arquivos de versão, metadados de pacote ou uma captura de tela/vídeo mais recente fornecida pelo usuário.

Fluxo de Trabalho

1. Ancorar o estado alvo

   • Confirme o nome do produto/aplicativo, branch, versão, nome do binário e escopo da plataforma a partir dos arquivos do repositório ou instruções explícitas do usuário.
   • Inspecione a implementação relevante ou strings de UI para as funcionalidades que estão sendo descritas.
   • Trate capturas de tela/vídeos mais recentes fornecidos pelo usuário como evidência visual autoritativa, a menos que o código ou o contexto da branch claramente os contradiga.

2. Atualizar documentos e mídia juntos

   • Substitua capturas de tela/GIFs desatualizadas quando a UI mudou.
   • Verifique se toda referência de imagem existe e aponta para o arquivo pretendido.
   • Verifique se as capturas de tela não contradizem visivelmente o nome atual do produto, rótulos de menu, versão ou estado da UI.
   • Remova referências de mídia antigas quando descrevem comportamento removido.
   • Para uma versão pública alimentada por um repositório privado, atualize os arquivos README públicos no repositório público em release/vX.Y.Z depois que o snapshot limpo for copiado para lá. Não confie no README privado como a fonte final de verdade pública.
   • Trate o CHANGELOG público, rascunhos de notas de release, documentos de instalação e logs de desenvolvimento públicos como parte do mesmo conjunto de documentos voltados para a release. Eles devem usar os mesmos nomes de produto, versão, nomes de ativos, declarações de privacidade e texto voltado ao usuário que o README.

3. Manter documentos bilíngues equivalentes

   • Compare as seções em inglês e japonês ponto a ponto.
   • Preserve os mesmos fatos do produto, ordem das funcionalidades, ressalvas e requisitos de configuração em ambos os idiomas.
   • Não deixe comportamento importante explicado em apenas um idioma.

4. Escrever cópia legível do README público

   • Torne as seções de primeira leitura escaneáveis: parágrafos curtos, uma ideia por parágrafo e linhas em branco onde melhoram a legibilidade.
   • Comece com o que o produto faz e o que o usuário pode ver ou fazer. Coloque detalhes de implementação depois, somente quando forem relevantes para configuração, segurança ou solução de problemas.
   • Prefira linhas claras de comportamento em vez de frases de funcionalidades densas. Um bom formato é uma visão geral de uma frase seguida por 2 a 4 linhas concisas de capacidade.
   • Para comportamento de UI, descreva o resultado visível: arrastar para mover, redimensionar a partir de uma borda ou canto, clicar duas vezes para redefinir. Evite detalhes internos do framework, como faixas de clique, retângulos de cursor, detalhes internos de dimensionamento ou percentuais exatos padrão, a menos que o usuário precise deles.
   • Mantenha informações detalhadas onde são genuinamente úteis, mas não faça o README público carregar explicações de implementação exclusivas do mantenedor.
   • Aplique a mesma regra de legibilidade às notas de release e entradas de changelog: evite precisão interna, como percentuais exatos padrão, texto de faixa de clique, mecânicas de retângulo de cursor ou detalhes triviais do sistema de compilação, a menos que afetem uma correção visível ao usuário, etapa de instalação ou caminho de solução de problemas.

5. Tornar amigável para leitores japoneses

   • Prefira termos de UI japoneses comuns quando naturais: タブ, 詳細パネル, マウスオーバー, 最小表示, フローティングタブ.
   • Mantenha literais técnicos como comandos, caminhos, nomes de pacotes, nomes de aplicativos, URLs e identificadores de código em inglês.
   • Remova listas de funcionalidades redundantes e parágrafos repetidos; torne o conjunto principal de funcionalidades rapidamente escaneável para um leitor japonês geral.

6. Examinar desvios desatualizados do produto

   • Nomes de produtos antigos, nomes de aplicativos antigos, nomes de binários antigos e nomes de repositórios antigos.
   • Números de versão antigos fora de entradas históricas de changelog.
   • Rótulos de UI obsoletos, notas de plataforma removidas e capturas de tela de comportamento mais antigo.
   • Alegações que implicam que uma dependência deve estar em execução quando apenas um CLI ou pacote instalado é necessário.

7. Validar antes de encerrar

   • Execute comandos relevantes de lint/verificação de documentos quando disponíveis.
   • Execute uma varredura rg limitada para nomes/versões/rótulos desatualizados.
   • Execute a varredura de texto desatualizado/privado/muito interno em arquivos README, changelogs, notas de release e quaisquer documentos públicos incluídos na release, não apenas no README de nível superior.
   • Verifique se os links de imagem do README existem.
   • Para PRs de release, forneça aos mantenedores as URLs do README renderizado pelo GitHub para o branch/PR e aguarde aprovação visual explícita. Isso deve corresponder à exibição do GitHub que os usuários realmente verão; prévias locais, Markdown bruto, capturas de tela estáticas ou verificações automatizadas são apenas evidências de apoio.
   • Inspecione o git diff do repositório público para que as alegações do README, metadados de versão, nomes de ativos de release e alterações de implementação copiadas estejam de acordo.
   • Para releases públicas, prefira branch release/vX.Y.Z -> PR -> CI -> merge antes da tag ou criação da Release do GitHub. Pushes diretos para main devem ser usados apenas quando o mantenedor solicitar explicitamente pular a validação do PR.
   • Se o código mudou, execute os testes ou compilação relevantes.
   • Resuma as verificações da fonte de verdade, não apenas os arquivos editados.

Lista de Verificação de Saída

Antes de finalizar, relate:

• nome do produto/versão/branch verificado;
• referências de mídia verificadas;
• paridade japonês/inglês verificada;
• aprovação visual do README renderizado pelo GitHub recebida, ou explicitamente ainda pendente;
• resultado da varredura de texto desatualizado;
• testes/compilação/verificações de documentos executados, ou por que não foram executados.