From 6a72195a1f950ea5a27cb51bf5fee52ab4576f0f Mon Sep 17 00:00:00 2001 From: Gabriel Jablonski Date: Sat, 11 Apr 2026 22:24:57 -0300 Subject: [PATCH] chore(release-notes): tighten skill format conventions (#262) - Render English block first, then Portuguese, with H2 country-flag headings outside the user-notes markers so GitHub viewers see clearly separated sections without affecting fazer.ai rendering - Document the full release body (Changes commit list + both locale sections) as the canonical example - Replace the non-existent `gh release edit` with `gh api PATCH` for backfills - Drop the unrealistic "cannot write equivalent" fallback clause --- .claude/skills/release-notes/SKILL.md | 79 ++++++++++++++++++--------- 1 file changed, 53 insertions(+), 26 deletions(-) diff --git a/.claude/skills/release-notes/SKILL.md b/.claude/skills/release-notes/SKILL.md index cb277c876..b6de39c13 100644 --- a/.claude/skills/release-notes/SKILL.md +++ b/.claude/skills/release-notes/SKILL.md @@ -10,21 +10,25 @@ Every release cut from `fazer-ai/chatwoot` must embed bilingual user-notes block ## Required blocks (bilingual, both mandatory) +The release body must contain both an English block and a Portuguese block, in this order. Use H2 headings with country flags **outside** the blocks to separate the two sections visually on GitHub. The fazer.ai page only renders the content **inside** the `` / `` markers, so the H2 headings, the flags, and any commit list above are invisible there. + ```markdown - -... markdown em português ... - +## 🇺🇸 English ... markdown in english ... + +## 🇧🇷 Português + + +... markdown em português ... + ``` The two versions must be **equivalent in content**, written naturally in each language. They are **not** literal translations: -- pt-BR: "Agora você pode arrastar conversas entre colunas mais rápido." - en: "Drag conversations between columns faster." - -If you cannot write a real equivalent in one of the locales, write a **generic line in both** instead of leaving one missing or pasting raw Google Translate output. +- pt-BR: "Agora você pode arrastar conversas entre colunas mais rápido." ## Audience and tone @@ -42,22 +46,17 @@ Write for an **end user, not a developer**. Readers do not read code, do not kno | `### ⚡ Melhorias` | `### ⚡ Improvements` | Refinements to existing features (perf, UX, polish) | | `### 🐛 Correções` | `### 🐛 Fixes` | Bugs the user might have noticed | -## Format inside each block +## Full release body example + +The release body should preserve the auto-generated `## Changes` commit list at the top and append both locale sections after it: ```markdown - -### ✨ Novidades +## Changes -- **Chat interno entre agentes.** Sua equipe agora troca mensagens diretamente dentro do Chatwoot, sem precisar de outra ferramenta. +- feat(internal-chat): implement internal chat system for agents (#247) +- fix(signatures): allow admins to manage inbox signatures without explicit membership (#260) -### ⚡ Melhorias - -- **Navegação mais rápida em conexões lentas.** A troca entre conversas ficou mais responsiva. - -### 🐛 Correções - -- **Assinaturas de caixas de entrada.** Administradores conseguem gerenciar assinaturas mesmo sem participar da caixa. - +## 🇺🇸 English ### ✨ What's new @@ -72,6 +71,22 @@ Write for an **end user, not a developer**. Readers do not read code, do not kno - **Inbox signatures.** Admins can manage signatures without having to be a member of the inbox. + +## 🇧🇷 Português + + +### ✨ Novidades + +- **Chat interno entre agentes.** Sua equipe agora troca mensagens diretamente dentro do Chatwoot, sem precisar de outra ferramenta. + +### ⚡ Melhorias + +- **Navegação mais rápida em conexões lentas.** A troca entre conversas ficou mais responsiva. + +### 🐛 Correções + +- **Assinaturas de caixas de entrada.** Administradores conseguem gerenciar assinaturas mesmo sem participar da caixa. + ``` Bold the change name, then a single short sentence describing the user benefit. Keep each item to 1 or 2 lines. @@ -79,20 +94,25 @@ Bold the change name, then a single short sentence describing the user benefit. If a release has nothing user-visible, write a single generic line in both locales rather than dumping a PR list: ```markdown - -Correções de bugs e melhorias internas. - +## 🇺🇸 English Bug fixes and internal improvements. + +## 🇧🇷 Português + + +Correções de bugs e melhorias internas. + ``` ## Quality checklist (run before publishing) Run this checklist on **both** locale blocks: -- [ ] Both `pt-BR` and `en` blocks are present, with the exact tag spelling shown above. +- [ ] Both `en` and `pt-BR` blocks are present, with the exact tag spelling shown above, and the `en` block comes first. +- [ ] Both sections are wrapped by `## 🇺🇸 English` / `## 🇧🇷 Português` H2 headings outside the markers. - [ ] Both blocks contain equivalent content (same items, same order, same themes), written naturally in each language. Not a literal translation. - [ ] Headers use the localized header table above. Omit empty themes consistently across locales. - [ ] Every item leads with a user benefit, not an implementation detail. @@ -120,8 +140,15 @@ When invoked for a release (new or backfill): 1. Read the current release body via `gh release view --json body -q .body` (or the source commits via `git log .. --oneline`) to understand what shipped. 2. Filter the changes through "would a non-technical operator notice or care about this?". Drop everything that fails the filter. 3. Group what survived into Novidades / Melhorias / Correções. -4. Draft the **pt-BR** block first. Write naturally, lead with benefit. +4. Draft the **pt-BR** block first as the source language. Write naturally, lead with benefit. 5. Draft the **en** block. Equivalent content, natural English, not a word-for-word translation. -6. Run the quality checklist on both blocks. -7. Show the proposed blocks to the user for approval **before** editing the release. -8. Only after approval, edit the release with `gh release edit --notes-file ` (preserve any existing technical body content above/below the blocks if present, or replace as the user instructs). +6. Assemble the full release body: keep the `## Changes` commit list at the top, then `## 🇺🇸 English` + the `en` block, then `## 🇧🇷 Português` + the `pt-BR` block. The `en` section always comes first in the rendered release body. +7. Run the quality checklist on both blocks. +8. Show the full proposed body to the user for approval **before** editing the release. +9. Only after approval, write the body to a temp file and apply it: + - **For new releases**, pass the file via `gh release create --notes-file `. + - **For backfills / edits**, this version of `gh` does not have a `release edit` subcommand. Use the API directly: + ```bash + RELEASE_ID=$(gh api repos///releases/tags/ --jq '.id') + gh api -X PATCH "repos///releases/$RELEASE_ID" -F body=@ + ```