gem-release

name	gem-release
description	Automates the complete process of releasing a new version of the openclacky Ruby gem. Supports both stable releases (auto-increment) and pre-release versions (user-specified, e.g., 1.0.0.beta.1). Handles version bumping, testing, building, RubyGems publishing, GitHub Releases, and OSS CDN mirroring.
disable-model-invocation	false
user-invocable	true

Gem Release Skill

Automates the complete openclacky gem release workflow via SKILL_DIR/scripts/release.sh.

Usage

• "Release a new version"
• "Publish a new gem version"
• "Release version 1.0.0.beta.1" (pre-release with explicit version)
• /gem-release

Workflow

The release script (SKILL_DIR/scripts/release.sh) handles everything end-to-end:

1. Pre-release checks (clean working directory, required tools)
2. Run test suite (bundle exec rspec) + web search smoke tests (real network — verifies Bing/DDG parsers still work against live HTML)
3. Bump version in lib/clacky/version.rb
4. Update Gemfile.lock via bundle install
5. Commit and push to origin, wait for CI
6. Build gem (gem build openclacky.gemspec)
7. Publish to RubyGems (gem push)
8. Create git tag and push
9. Create GitHub Release with .gem asset (uses CHANGELOG.md for notes)
10. Upload .gem to Tencent Cloud OSS CDN
11. Update latest.txt on OSS (stable only, unless --update-latest)
12. Rebuild and sync scripts/ to OSS
13. Cleanup build artifacts

Agent Instructions

1. Determine version and release type

Read current version:

grep 'VERSION =' lib/clacky/version.rb

Stable release (default): Increment patch version (e.g., 1.0.5 → 1.0.6). Confirm with user if unsure which part to bump (major/minor/patch).

Pre-release: Use the exact version the user specified (e.g., 2.0.0.beta.1). Before proceeding, warn about pre-release caveats (see section below).

2. Write CHANGELOG

This is the one step the agent handles manually — the script does not write changelog entries because it requires reviewing git history and exercising judgment.

1. Find the previous version tag:

   git describe --tags --abbrev=0
   

2. Gather commits since last release:

   git log <previous_tag>..HEAD --oneline
   

3. Write a new section in CHANGELOG.md following this format:

   ## [X.Y.Z] - YYYY-MM-DD
   
   ### Added
   - Feature description
   
   ### Improved
   - Enhancement description
   
   ### Fixed
   - Bug fix description
   
   ### More
   - Minor items
   

4. Categorization rules:

   • Each commit with independent user-facing value gets its own bullet — don't over-merge commits sharing a theme
   • Use imperative mood ("Add" not "Added")
   • Place user-facing value at the top
   • Skip trivial commits (typos, minor formatting)
   • Sanity check: count ### Added bullets vs feat: commits — if commits > bullets, you likely merged too aggressively

5. External contributor attribution:

   • For PRs from non-clacky-ai org members, append (#PR_NUMBER - @username) to the bullet
   • Query org members to distinguish external contributors:

     gh api orgs/clacky-ai/members --paginate --jq '.[].login' | sort
     

   • Then cross-reference PR authors in the release range:

     git log <previous_tag>..HEAD --oneline | grep -oP '#\d+' | while read pr; do
       num=${pr#\#}
       gh pr view $num --json number,author --jq '"#\(.number) \(.author.login)"'
     done
     

3. Run the release script

Stable release:

bash "SKILL_DIR/scripts/release.sh" <version>

Pre-release (skip latest.txt):

bash "SKILL_DIR/scripts/release.sh" <version> --prerelease

Pre-release (update latest.txt — only if user explicitly requested):

bash "SKILL_DIR/scripts/release.sh" <version> --prerelease --update-latest

Dry run (preview only):

bash "SKILL_DIR/scripts/release.sh" <version> --dry-run

The script runs all steps sequentially and stops on any failure. Monitor the output — if a step fails, diagnose and fix before retrying.

4. Present release summary

After the script completes successfully, present a concise summary. The output will often be read in WeChat, so keep it compact and avoid template-like formatting that triggers message folding.

Rules:

• No emojis
• No tables (use a compact list if you need to list items)
• No multi-line code blocks
• Write as a natural, flowing message — not a structured report
• Skip "More" / chore items unless they directly affect users
• Write from the user's perspective — what they can now do, or what problem is fixed
• Translate technical terms into plain language
• Keep each item one sentence, action-oriented

Format (flexible — adapt as needed, but roughly):

v{version} released.

[One sentence highlight — the biggest user-visible change.]

Added:
- [translate each "Added" item]
- ...

Improved:
- [translate each "Improved" item]
- ...

Fixed:
- [translate each "Fixed" item]
- ...

Upgrade: click "Upgrade" in Web UI bottom-left, or `gem update openclacky`
Fresh install: curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh | bash

RubyGems: https://rubygems.org/gems/openclacky/versions/{version}
GitHub: https://github.com/clacky-ai/openclacky/releases/tag/v{version}

Pre-Release Caveats

When releasing a pre-release version, inform the user of these behaviors:

Concern	Behavior	Impact
Version check notification	Gem::Version("0.9.38") < Gem::Version("1.0.0.beta.1") is true	The upgrade dot WILL appear in the Web UI for most users
gem update (official source)	Does NOT install prereleases without --pre	Users who click "Upgrade" will see notification but upgrade silently does nothing
OSS CDN upgrade (mirror users)	Downloads exact .gem from latest.txt	If latest.txt points to prerelease, mirror users WILL get the beta
OSS latest.txt	Fresh installs fetch latest.txt	By default, do NOT update latest.txt for pre-releases

Ask the user whether to use --update-latest before running the script.

Error Handling

The script uses set -euo pipefail and stops on any failure. Common issues:

• Tests fail → fix tests before re-running
• Web search smoke test fails (Bing) → This often happens due to datacenter IP fingerprinting (anti-scrape blocking) returning irrelevant top-domain filler (like Mr.Bricolage). If you see "No ruby-related result from bing" during the smoke test:
  1. Manually run bundle exec rspec spec/integration/web_search_smoke_spec.rb --tag smoke to verify
  2. If it's the anti-scrape block, temporarily edit spec/integration/web_search_smoke_spec.rb to skip the relevance check on failure (e.g., using skip "Bing returned anti-scrape garbage...")
  3. Commit the change ("ci: skip bing smoke test relevance check on anti-scrape") and re-run the release script
• CI fails → script pushes then watches CI; fix and re-push if needed
• gem push fails → check RubyGems credentials (gem signin)
• gh release fails → check gh auth status
• coscli fails → check ~/.cos.yaml config

After fixing an issue, you can re-run the script — it's safe to retry. If a partial release happened (e.g., gem pushed but tag not created), handle remaining steps manually.

File Locations

• Release script: SKILL_DIR/scripts/release.sh
• Version file: lib/clacky/version.rb
• Gem specification: openclacky.gemspec
• Changelog: CHANGELOG.md

Dependencies

• Ruby >= 3.1.0, Bundler, RSpec
• gh CLI installed and authenticated
• coscli installed at /usr/local/bin/coscli with ~/.cos.yaml
• RubyGems push credentials