GitHub Release

When to Use

• Publishing a new version (patch / minor / major)
• Writing or updating release notes for an existing tag
• Fixing garbled characters (question marks, mojibake) in release notes caused by Unicode homoglyphs

Procedure

Step 1: Collect changes since last tag

git log --oneline <last-tag>..HEAD
git diff <last-tag>..HEAD --stat
gh release view <last-tag>   # reference previous notes format

Step 2: Create and push tag

git tag -a <new-tag> -m "release: <new-tag>"
git push origin <new-tag>

Step 3: Write release notes to a temp file

Write notes to .release_notes_tmp.md using create_file tool -- never inline in the shell command.

See release-notes-template.md for the recommended structure.

Step 4: Verify pure ASCII (required)

python3 -c "
import sys
data = open('.release_notes_tmp.md', encoding='utf-8').read()
bad = [(i, c, ord(c)) for i, c in enumerate(data) if ord(c) > 127]
print(f'Non-ASCII count: {len(bad)}')
for idx, ch, cp in bad:
    print(f'  index {idx}: U+{cp:04X}  repr={ch!r}')
if bad: sys.exit(1)
"

Expected output: Non-ASCII count: 0 and exit code 0.
If any characters are found, consult ascii-replacements.md and fix before continuing.

Step 5: Create release

gh release create <new-tag> --title "<new-tag>" --notes-file .release_notes_tmp.md

Step 6: Cleanup

rm .release_notes_tmp.md

Step 7 (fix existing release): Edit release notes

gh release edit <tag> --notes-file .release_notes_tmp.md
rm .release_notes_tmp.md

Key Constraints

• Never pass AI-generated text as an inline --notes "..." argument -- Unicode homoglyphs (e.g. Cyrillic a U+0430 disguised as Latin a) survive copy-paste and corrupt the published notes.
• Always use --notes-file with a file that has passed the ASCII verification step.
• Keep .release_notes_tmp.md out of version control (add to .gitignore).

References

• release-notes-template.md -- recommended notes structure
• ascii-replacements.md -- common Unicode-to-ASCII replacement table