Skip to content

chore(skills): review README and repo about text on every release #1429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
carlos-alm merged 4 commits into from
Jun 10, 2026
Merged

chore(skills): review README and repo about text on every release #1429

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7e862f4
chore(skills): review README and repo about text on every release
carlos-alm Jun 10, 2026
1a69fac
fix(skills): reinforce PUT /topics full-replace semantics and add abo…
carlos-alm Jun 10, 2026
246fec3
Merge branch 'main' into chore/release-skill-about-text
carlos-alm Jun 10, 2026
6db4d11
Merge branch 'main' into chore/release-skill-about-text
carlos-alm Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 41 additions & 3 deletions .claude/skills/release/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,11 @@ Read `docs/roadmap/BACKLOG.md` and check if any backlog items were completed or
- Check the "Depends on" column of other items — if they depended on the newly completed item, note that they are now unblocked
- Update the `Last updated` date at the top of the file

## Step 5: Update README.md
## Step 5: Update README.md and repo "about" text

This step runs every release regardless of whether features changed.

### README.md

Read `README.md` and check if any new user-facing features from this release need to be documented:

Expand All @@ -175,7 +179,37 @@ Read `README.md` and check if any new user-facing features from this release nee
- Completed phases should keep their historical version markers (e.g., "Complete (v3.0.0)")
- This check runs every release, not only when phase status changes — drift accumulates silently
6. **Version references** — only update version-specific references (e.g., install commands). Historical milestone markers like "Complete (v3.0.0)" should stay as-is
7. If nothing user-facing changed (pure refactors, bug fixes, internal improvements), no README update is needed — **but still run the roadmap ordering cross-check (item 5)**
7. If nothing user-facing changed (pure refactors, bug fixes, internal improvements), no README content update is needed — **but still run the roadmap ordering cross-check (item 5)**

### Repo "about" text

Fetch the current GitHub repository metadata and review whether it still accurately describes the project:

```bash
gh api repos/optave/ops-codegraph-tool --jq '{description: .description, homepage: .homepage, topics: .topics}'
```

Check:
- **Description** — does the one-line repo description match what codegraph actually is and does today? Update if it's stale, vague, or missing newly supported languages/capabilities.
- **Topics/tags** — are the labels current? For example, if a new language was added this release, add it. Common topics to keep in sync: language names, `cli`, `code-analysis`, `dependency-graph`, `tree-sitter`, `sqlite`, `mcp`.
- **Homepage** — is the URL still correct?

If any field needs updating, apply it **directly via the API** (no file change needed — this is a GitHub metadata update, not a committed file):

```bash
# Update description and/or homepage
gh api --method PATCH repos/optave/ops-codegraph-tool \
-f description="NEW DESCRIPTION" \
-f homepage="https://..."

# Update topics — start from the fetched list above, then add/remove as needed.
# This PUT replaces ALL topics atomically; do NOT copy the example below verbatim —
# build the full list from the currently active topics first, then adjust.
gh api --method PUT repos/optave/ops-codegraph-tool/topics \
-f "names[]=cli" -f "names[]=code-analysis" -f "names[]=dependency-graph" -f "names[]=tree-sitter"
```

Comment on lines +199 to +211

@greptile-apps greptile-apps Bot Jun 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Full-replace semantics not reinforced before the example command

PUT /repos/{owner}/{repo}/topics replaces the complete topics list atomically. The inline note says "replaces the full list — include all desired topics," but the example command only enumerates four topics. An agent that uses the example as a near-literal template (rather than building the list from the fetched topics in the earlier gh api call) would silently drop any topics not in that hardcoded example. Prefacing the command with an explicit instruction to start from the fetched list — e.g., "Merge the fetched topics with any additions/removals before running the PUT; do not rely on the example list below" — would prevent accidental topic loss.

Fix in Claude Code

@carlos-alm carlos-alm Jun 10, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed — added two comment lines before the PUT example making the full-replace semantics explicit: 'start from the fetched list above, then add/remove as needed' and 'This PUT replaces ALL topics atomically; do NOT copy the example below verbatim — build the full list from the currently active topics first, then adjust.'

Note: "about" text changes are applied directly to GitHub — they don't require a commit. Record any changes made in the PR description so reviewers know what was updated.

## Step 6: Verify `libc` fields in package-lock.json

Expand All @@ -200,19 +234,23 @@ Place the `libc` array after the `cpu` array in each entry.
2. Stage only the files you changed: `CHANGELOG.md`, `docs/roadmap/ROADMAP.md`, `docs/roadmap/BACKLOG.md` if changed, `README.md` if changed, `package-lock.json` if libc fields were fixed
3. Commit: `docs: prepare release notes for vVERSION`
4. Push: `git push -u origin release/VERSION`
5. Create PR:
5. Create PR (include a note if repo "about" text was updated directly on GitHub):

```
gh pr create --title "docs: prepare release notes for vVERSION" --body "$(cat <<'EOF'
## Summary
- Add CHANGELOG entry for vVERSION (all commits since previous release)
- Update ROADMAP progress
- Review README and repo "about" text for accuracy
- Repo "about" updated: <!-- describe what changed (description / homepage / topics), or "no changes needed" -->

**After merging:** create a GitHub Release with tag `vVERSION` to trigger the publish workflow, which handles version bumping, native binary builds, and npm publishing.

## Test plan
- [ ] CHANGELOG renders correctly on GitHub
- [ ] ROADMAP checklist items match actual codebase state
- [ ] README roadmap order matches ROADMAP.md
- [ ] Repo "about" description and topics are current
EOF
)"
```
Expand Down
Loading