[EPIC #60] Enrich version management UX: upgrade output, release blog, contextual help#61
Merged
[EPIC #60] Enrich version management UX: upgrade output, release blog, contextual help#61
Conversation
- Add 'Generate blog post stub for new major version' step in the snapshot CI job: creates docs/blog/release-vX-0-0.md idempotently - Extend git-auto-commit step to include docs/blog/ alongside versions.json - Make blog sidebar dynamically generated from docs/blog/*.md files in config.mts so new stubs appear in the nav without a manual config PR Part of #60, closes #57
- Add html_url to GithubRelease interface - Add blogPostUrl() helper to derive doc blog URL from release tag - Replace 'Already up to date' with friendlier 'Congrats!' message - After successful upgrade print: Welcome message, What's new blog link, GitHub release notes link, commit comparison URL, bug-report link - Add checkForUpdate() pure helper: returns latest tag or null (swallows errors) - Update tests: add html_url to all fixtures, cover new messages, add full checkForUpdate test suite (36 tests pass) Part of #60, closes #55, closes #51
[#58] Deep documentation links in CLI help: - program --help shows 'Documentation: https://fulll.github.io/github-code-search/' - upgrade --help points to /usage/upgrade - query --help points to /usage/search-syntax - --exclude-repositories/--exclude-extracts mention /usage/filtering - --format/--output-type mention /usage/output-formats - --group-by-team-prefix mentions /usage/team-grouping [#59] Update-available notice after non-interactive search: - import checkForUpdate() from upgrade.ts - After CI/non-interactive output, race a 2s timeout against checkForUpdate - If a newer version exists, print a yellow framed notice to stderr (never pollutes piped stdout, never shown in interactive TUI mode) Also fix toSorted/toReversed lint warnings in config.mts Part of #60, closes #58, closes #59
|
Coverage after merging feat/version-management-ux into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
Improves the UX around version management by enriching upgrade output, adding a VitePress “What’s New” release blog section, and adding contextual documentation links + update notifications in the CLI.
Changes:
- Enriched
upgrademessaging (release/blog links, compare URL, bug link) and addedcheckForUpdate()for silent version checks. - Added docs blog pages + dynamic blog sidebar + nav entry.
- Added contextual docs links in CLI help, plus an update-available notice after non-interactive searches.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/upgrade.ts | Adds release html_url, blog URL helper, richer upgrade output, and checkForUpdate() helper. |
| src/upgrade.test.ts | Updates fixtures/tests for html_url, blogPostUrl(), checkForUpdate(), and new upgrade output. |
| github-code-search.ts | Adds contextual docs links to help output and prints update-available notice after non-interactive output. |
| docs/blog/index.md | Adds the release blog index page. |
| docs/blog/release-v1-0-0.md | Adds an initial release highlights post. |
| docs/.vitepress/config.mts | Adds “What’s New” nav entry and builds /blog/ sidebar items dynamically from docs/blog/*.md. |
| .github/workflows/docs.yml | Generates/commits a major-release blog stub alongside versions.json during snapshot tagging. |
- Add HAS_COLOR guard (process.stdout.isTTY) — pipes and CI stay plain-text
- Add helpFormatConfig with Commander v14 style hooks:
styleTitle → bold yellow (Usage:, Options:, Commands: …)
styleCommandText → bold (github-code-search name)
styleSubcommandText / styleSubcommandTerm → cyan (upgrade, query)
styleArgumentText / styleArgumentTerm → yellow (<query>)
styleOptionText / styleOptionTerm → green (--org, --format …)
styleOptionDescription + siblings → colorDesc():
• 'Docs: <url>' → dim label + cyan underlined URL
• 'Example: ...' → dim label + italic value
• Code-example lines (e.g. / repoA / myorg) → dim
- Add helpLink() and helpSection() helpers; update all addHelpText('after',…)
calls to use them so 'Documentation:' labels are bold and URLs are cyan+underline
- Apply configureHelp(helpFormatConfig) to program, upgrade and query commands
Part of #60
|
Coverage after merging feat/version-management-ux into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- Fix blogPostUrl() no-op replace: normalize tag to always have v-prefix
before slug-ifying (replace(/^v/, 'v') → \`v${tag.replace(/^v/, '')}\`)
- Add AbortController to checkForUpdate timeout race so the in-flight
fetch is actually cancelled when the 2s deadline fires (github-code-search.ts)
- Pass AbortSignal through checkForUpdate → fetchLatestRelease
- Fix ESM __dirname usage in docs/.vitepress/config.mts: use
fileURLToPath(new URL('../blog', import.meta.url)) instead of
resolve(__dirname, '../blog') which may be undefined in ESM
- Add semantic version sort for blog sidebar: parseBlogVersion() +
compareVersionArrays() helpers replace lexicographic toSorted().toReversed()
so multi-digit versions (v1.10.0) sort correctly before v1.9.0
- Replace malformed sed command in docs.yml blog index update with a
Python heredoc script that reliably inserts the new table row
- Pin stefanzweifel/git-auto-commit-action to commit SHA 8621497c
(v5.0.1) to prevent supply-chain attacks flagged by GH Advanced Security
|
Coverage after merging feat/version-management-ux into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
…iles - Add '## Release process' section to AGENTS.md covering: - semver decision table (patch / minor / major) - step-by-step release commands (bun pm version, tag, push) - what cd.yaml and docs.yml do automatically on each tag type - blog post convention (required for minor/major, optional for patch) - Add step 8 to bug-fixing.instructions.md: patch release after merge - Add step 8 to implement-feature.instructions.md: minor/major release after merge, including blog post reminder
|
Coverage after merging feat/version-management-ux into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
New features in this release: - Enriched upgrade output: blog post URL, release notes link, commit log - Update-available notice printed on stderr after CI/non-interactive searches - Colorized --help output (Commander style hooks, picocolors) - Deep documentation links in every --help text - What's New blog section in VitePress docs with per-release posts - CI: auto-generate blog stub for major release tags
|
Coverage after merging feat/version-management-ux into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- Fix update notice box: corners and side bars were different widths (header used w-18 constant; corrected using totalWidth formula so all four sides are exactly w+4 characters wide) - Fix docs.yml heredoc: blog stub was written with leading whitespace on every line (breaking YAML frontmatter); replaced with Python that writes the file programmatically, indented correctly for the YAML block - Add test for already-aborted AbortSignal in checkForUpdate: verifies the function silently returns null when the signal is pre-aborted - Fix 'organization' → 'organisation' in release-v1-0-0.md (British spelling consistent with the rest of the documentation)
|
Coverage after merging feat/version-management-ux into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #55, closes #56, closes #57, closes #58, closes #59, closes #51.
Part of epic #60.
What changed
src/upgrade.tshtml_urlto theGithubReleaseinterfaceblogPostUrl(tag)pure helper: derives the VitePress blog post URL from a release tagcheckForUpdate(currentVersion, token?): silently returns the latest tag ornull(never throws)src/upgrade.test.tshtml_urlto all release fixturesblogPostUrltest suitecheckForUpdatetest suite (5 cases: newer version, up-to-date, dev, network error, API 404)performUpgradeassertions for the new "Welcome" / "Congrats" messagesdocs/blog/docs/blog/index.md: listing page for all release postsdocs/blog/release-v1-0-0.md: v1 series highlightsdocs/.vitepress/config.mts/blog/docs/blog/*.md— new CI-generated stubs appear automatically without a manual config PR.github/workflows/docs.ymlsnapshotjob: auto-generatedocs/blog/release-vX-0-0.mdon everyvX.0.0tag (idempotent)git-auto-commit-actionto commitdocs/blog/alongsideversions.jsongithub-code-search.tscheckForUpdatefromsrc/upgrade.tsprogram --helpfooter:Documentation: https://fulll.github.io/github-code-search/upgrade --helpfooter: links to/usage/upgradequery --helpfooter: links to/usage/search-syntax--exclude-repositories/--exclude-extracts: mention/usage/filtering--format/--output-type: mention/usage/output-formats--group-by-team-prefix: mention/usage/team-groupingcheckForUpdateagainst a 2 s timeout; if a newer version exists, print a yellow framed notice to stderr (never pollutes piped stdout, never shown in TUI mode)Validation