Implement internal changeset script for version management with safety checks by Copilot · Pull Request #1343 · github/gh-aw

Copilot · 2025-10-08T05:08:01Z

This PR implements a minimalistic changeset script inspired by @changesets/cli for managing version releases in gh-aw. The implementation provides a streamlined workflow for tracking changes, determining version bumps, and updating the CHANGELOG. This is an internal tool for project maintainers and is not included in public CLI documentation.

Problem Statement

The project needed a simple way to:

Track changes across multiple contributions
Automatically determine appropriate version bumps (major/minor/patch)
Generate and maintain a CHANGELOG
Automate the release preparation process
Preview changes before committing
Ensure releases are created safely from clean state on main branch

Solution

Added a standalone JavaScript script in scripts/changeset.js that can be run directly with Node.js or via Makefile targets:

`node scripts/changeset.js version`

Analyzes changeset files in .changeset/ directory and previews the next release (always read-only):

$ node scripts/changeset.js version
ℹ Current version: v0.14.3
ℹ Bump type: minor
ℹ Next version: v0.15.0
ℹ Changes:
  [minor] Add PR branch checkout when pull request context is available
  [minor] Add secret redaction step before artifact upload
  [patch] Convert TypeScript safe output files to CommonJS

ℹ Would add to CHANGELOG.md:
---
## v0.15.0 - 2025-10-08

### Features
- Add PR branch checkout when pull request context is available
- Add secret redaction step before artifact upload

### Bug Fixes
- Convert TypeScript safe output files to CommonJS
---

`node scripts/changeset.js release [type]`

Creates a release by updating CHANGELOG.md and cleaning up changeset files:

$ node scripts/changeset.js release
ℹ Creating minor release: v0.15.0
✓ Updated CHANGELOG.md
✓ Removed 3 changeset file(s)
ℹ Next steps:
  1. Review CHANGELOG.md
  2. Commit changes: git add CHANGELOG.md .changeset/ && git commit -m "Release v0.15.0"
  3. Create tag: git tag -a v0.15.0 -m "Release v0.15.0"
  4. Push: git push origin v0.15.0

Safety Checks

Before creating a release, the script validates:

Clean working tree: All changes must be committed or stashed
On main branch: Must be on the main branch to create a release

$ node scripts/changeset.js release
✗ Must be on 'main' branch to create a release (currently on 'feature-branch')

Makefile Targets

Convenience targets for common operations:

make changeset-version    # Preview next version
make changeset-release    # Create release

Implementation Details

Changeset File Format:

---
"gh-aw": patch
---

Brief description of the change

Key Features:

Parses YAML frontmatter from changeset markdown files
Determines highest priority version bump (major > minor > patch)
Generates CHANGELOG entries categorized by type (Breaking Changes, Features, Bug Fixes)
Uses git tags to determine current version
Follows semantic versioning (major.minor.patch)
Requires explicit specification for major releases (safety feature)
Git prerequisite checks ensure clean state and main branch before release
Simplified two-command interface: version always previews (never modifies), release creates actual release
Makefile integration for convenient command execution
Consistent push behavior matching existing patch-release and minor-release targets (tag only)
Zero dependencies - pure Node.js implementation

Files Added:

scripts/changeset.js - Standalone Node.js script with safety checks and simplified commands
CHANGESET_README.md - Internal documentation for maintainers
Makefile - Added changeset-version and changeset-release targets

Note: This is an internal tool for project maintainers. It is not documented in the public CLI documentation (docs/src/content/docs/tools/cli.md) as it is not intended for general user consumption.

Testing

Manual testing confirms all functionality works correctly:

✅ Changeset file parsing (valid/invalid formats)
✅ Version bump determination logic
✅ Version formatting and incrementing
✅ CHANGELOG generation and updates
✅ Version command never modifies files
✅ Git prerequisite checks (clean tree, main branch)
✅ Makefile targets execute correctly
✅ Push instructions match existing release targets
✅ Edge cases (empty changesets, version ordering, etc.)
✅ All existing tests continue to pass

Usage (For Maintainers)

Add changeset files for each change to .changeset/ directory
Run node scripts/changeset.js version to preview the next release
Ensure you're on main branch with a clean working tree
Run node scripts/changeset.js release to prepare the release
Review CHANGELOG.md and commit changes
Create and push git tag

This provides a simple, standalone script for managing releases without requiring CLI integration or external dependencies. The script can be run anywhere Node.js is installed, includes safety checks to prevent accidental releases, and has a clear distinction between preview (version) and action (release) commands.

Original prompt

Implement a minimalistic implementation of https://www.npmjs.com/package/@changesets/cli that takes the files in the .changesets folder, decide what kind of release is needed, update changelog.md, then the logic to do a patch or minor release commit.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

- Add 'gh aw changeset' command with 'version' and 'release' subcommands - Parse changeset files from .changeset/ directory - Determine version bump based on changeset types (major/minor/patch) - Generate and update CHANGELOG.md with categorized changes - Delete processed changeset files on release - Add comprehensive tests for all changeset functionality Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

- Add changeset command section to CLI documentation - Include changeset file format examples - Document version and release commands - Add changeset commands to quick start guide - Explain release workflow and next steps Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan · 2025-10-08T05:25:59Z

@copilot add implementation as a separate javascript script, not in the CLI.

Clarify that major releases require explicit 'gh aw changeset release major' command and will fail with safety error if changesets indicate major bump but no type is specified. Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

@pelikhan

Per @pelikhan's request, moved changeset logic from Go CLI to a standalone JavaScript script (changeset.js). This provides a simpler, dependency-free implementation that can be run directly with Node.js. Changes: - Remove pkg/cli/changeset_command.go and tests - Revert cmd/gh-aw/main.go to remove changeset command - Add changeset.js standalone script with full implementation - Add CHANGESET_README.md with usage documentation - Update docs/src/content/docs/tools/cli.md to reference script The JavaScript implementation provides the same functionality: - node changeset.js version - Preview next version - node changeset.js release - Create release and update CHANGELOG Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2025-10-08T05:37:42Z

@copilot add implementation as a separate javascript script, not in the CLI.

Refactored to standalone JavaScript script in commit 3c5ff90. The changeset logic is now in changeset.js which can be run directly with Node.js:

node changeset.js version   # Preview next version
node changeset.js release   # Create release

See CHANGESET_README.md for full documentation.

pelikhan · 2025-10-08T05:51:13Z

@copilot add a --dry-run mode to the script to preview output but not write files or create release.

Run script in dry-run mode and show output

Implements dry-run mode that previews changes without modifying files: - Add --dry-run flag support to both version and release commands - Show "DRY RUN MODE" indicator when enabled - Display CHANGELOG entry that would be added - List changeset files that would be deleted - Update help text and documentation - Preserve all original functionality when flag not used Usage: node changeset.js version --dry-run node changeset.js release --dry-run node changeset.js release minor --dry-run Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2025-10-08T05:57:27Z

@copilot add a --dry-run mode to the script to preview output but not write files or create release.

Run script in dry-run mode and show output

Added --dry-run mode in commit d5c5e93. The flag can be used with both commands:

node changeset.js version --dry-run
node changeset.js release --dry-run

Dry-run output showing preview without modifying files:

$ node changeset.js release --dry-run
ℹ 🔍 DRY RUN MODE - No files will be modified

ℹ Creating minor release: v0.15.0

ℹ Would add to CHANGELOG.md:
---
## v0.15.0 - 2025-10-08

### Features

- Add PR branch checkout when pull request context is available
- Add secret redaction step before artifact upload in agentic workflows

### Bug Fixes

- Convert TypeScript safe output files to CommonJS and remove TypeScript compilation


---

ℹ Would remove 3 changeset file(s):
  - .changeset/minor-add-pr-branch-checkout.md
  - .changeset/minor-add-secret-redaction-step.md
  - .changeset/patch-convert-ts-safe-files-to-cjs.md

ℹ Next steps:
  1. Review CHANGELOG.md
  2. Commit changes: git add CHANGELOG.md .changeset/ && git commit -m "Release v0.15.0"
  3. Create tag: git tag -a v0.15.0 -m "Release v0.15.0"
  4. Push: git push origin main v0.15.0

pelikhan

@copilot

add check to make sure tree is clean and on main branch
add a makefile target that runs the changesets script

pelikhan · 2025-10-08T12:06:22Z

 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
 	github.com/sourcegraph/conc v0.3.0
 	github.com/spf13/cobra v1.9.1
+	gopkg.in/yaml.v3 v3.0.1


@copilot use existing yaml package, do not add new one

Fixed in commit (pending). Reverted go.mod and go.sum to remove the gopkg.in/yaml.v3 dependency that was accidentally added. The changeset script is JavaScript-only and doesn't use Go YAML packages.

- Add prerequisite checks: clean tree and main branch requirement - Add checkGitPrerequisites() function that validates: - Working tree is clean (no uncommitted changes) - Currently on 'main' branch - Checks are skipped in dry-run mode for flexibility - Add Makefile targets: - make changeset-version: Preview next version - make changeset-release: Create release - make changeset-dry-run: Preview without modifying files - Update documentation with prerequisites and make targets - Revert go.mod/go.sum to remove unnecessary yaml.v3 dependency The release command now ensures safety by requiring clean state and main branch before allowing actual releases. Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2025-10-08T12:15:47Z

@copilot

add check to make sure tree is clean and on main branch

add a makefile target that runs the changesets script

Added in commit (pending). The script now:

Checks git prerequisites before release:
- Validates working tree is clean
- Ensures on main branch
- Skips checks in --dry-run mode
Added Makefile targets:
- make changeset-version - Preview next version
- make changeset-release - Create release
- make changeset-dry-run - Preview without modifying files

Example error when not on main:

$ node changeset.js release
✗ Must be on 'main' branch to create a release (currently on 'feature-branch')

pelikhan · 2025-10-08T12:19:17Z

@copilot

validate the release script has the same branch naming as patch-release, minor-release
is there a difference between version and dry-run commands? Simplify.

pelikhan · 2025-10-08T12:20:23Z

 gh aw logs ci-doctor                             # View execution logs
 gh aw audit 12345678                             # Audit a specific run
+
+# Release management


@copilot internal release tool, remove from these docs

Removed in commit (pending). Reverted the file to its original state before changeset documentation was added.

pelikhan · 2025-10-08T12:20:44Z

 - **`disable`**: Stops workflows from executing automatically and cancels any currently running workflow instances
 - Both commands support pattern matching to operate on multiple workflows at once

+## 📦 Release Management with Changesets


@copilot remove changes from this file

Removed in commit (pending). All changeset-related changes have been reverted from this file.

Changes: - Simplify version command: always operates in preview mode (never writes files) - Remove --dry-run flag from version command (unnecessary since it never modifies) - Clarify that --dry-run is only for release command - Fix push instruction to match patch-release/minor-release format: Changed from "git push origin main v0.15.0" to "git push origin v0.15.0" (Only push the tag, not the branch) - Update all documentation to reflect simplified workflow - Update help text to clarify command usage This makes the distinction clear: - version: Always preview, never modify files - release: Actually modify files (unless --dry-run specified) - release --dry-run: Preview changes without modifying files Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2025-10-08T12:25:15Z

@copilot

validate the release script has the same branch naming as patch-release, minor-release

is there a difference between version and dry-run commands? Simplify.

Fixed in commit ad053ef:

Branch naming aligned: Changed push instruction from git push origin main v0.15.0 to git push origin v0.15.0 to match patch-release and minor-release targets (only push tag, not branch).
Simplified commands:
- version now always previews (never modifies files)
- Removed --dry-run from version command
- release --dry-run is the only dry-run option
- Clear distinction: version = preview, release = action

Example:

$ node changeset.js version
# Always shows preview, never writes files

$ node changeset.js release --dry-run  
# Preview release changes

$ node changeset.js release
# Actually create release

@pelikhan

Per @pelikhan's feedback, the changeset tool is an internal release tool and should not be documented in the public CLI documentation. Reverted docs/src/content/docs/tools/cli.md to original state before changeset documentation was added. The changeset functionality is still available via: - changeset.js script - CHANGESET_README.md documentation - Makefile targets (changeset-version, changeset-release, changeset-dry-run) Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan · 2025-10-08T12:34:45Z

@copilot remove --dry-run as it is the same as the version command

@pelikhan

Per @pelikhan's feedback, --dry-run is redundant since the version command already provides preview functionality without modifying files. Changes: - Remove --dry-run flag support from changeset.js - Remove dryRun parameters from all functions - Simplify release command to always modify files - Remove changeset-dry-run Makefile target - Update help text to remove --dry-run references - Update CHANGESET_README.md to remove dry-run documentation Now the workflow is simpler: - version: Always previews (never modifies files) - release: Always creates release (modifies files) Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2025-10-08T12:39:51Z

@copilot remove --dry-run as it is the same as the version command

Removed in commit (pending). The --dry-run flag has been completely removed from the script. Now:

version - Always previews (never modifies files)
release - Always creates release (modifies files)

The changeset-dry-run Makefile target has also been removed.

pelikhan · 2025-10-08T12:42:04Z

@copilot run preview and show output

Copilot · 2025-10-08T12:43:42Z

@copilot run preview and show output

Preview output from node changeset.js version:

ℹ Current version: v0.14.3
ℹ Bump type: minor
ℹ Next version: v0.15.0
ℹ 
Changes:
  [minor] Add PR branch checkout when pull request context is available
  [minor] Add secret redaction step before artifact upload in agentic workflows
  [patch] Convert TypeScript safe output files to CommonJS and remove TypeScript compilation

ℹ Would add to CHANGELOG.md:
---
## v0.15.0 - 2025-10-08

### Features

- Add PR branch checkout when pull request context is available
- Add secret redaction step before artifact upload in agentic workflows

### Bug Fixes

- Convert TypeScript safe output files to CommonJS and remove TypeScript compilation


---

The preview command analyzes the 3 changeset files in .changeset/, determines a minor version bump is needed (based on the 2 minor changesets), and shows what would be added to CHANGELOG.md without modifying any files.

pelikhan · 2025-10-08T12:56:36Z

@@ -0,0 +1,507 @@
+#!/usr/bin/env node


@copilot move to scripts folder (create)

Moved to scripts/ folder in commit (pending). Updated all references in Makefile, CHANGESET_README.md, and the script's help text.

@pelikhan

Per @pelikhan's request, moved changeset.js to scripts/ folder for better project organization. Changes: - Create scripts/ folder - Move changeset.js to scripts/changeset.js - Update Makefile targets to use scripts/changeset.js - Update CHANGESET_README.md with new path references - Update help text in script to reflect new path All functionality remains the same, just better organized. Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Initial plan

609e6b6

Copilot AI assigned Copilot and pelikhan Oct 8, 2025

Copilot started work on behalf of pelikhan October 8, 2025 05:08 View session

Copilot AI and others added 2 commits October 8, 2025 05:21

Copilot AI changed the title ~~[WIP] Add minimal implementation for changesets CLI integration~~ Implement changeset CLI for version management Oct 8, 2025

Copilot AI requested a review from pelikhan October 8, 2025 05:28

Copilot finished work on behalf of pelikhan October 8, 2025 05:28

Copilot started work on behalf of pelikhan October 8, 2025 05:29 View session

Copilot AI changed the title ~~Implement changeset CLI for version management~~ Implement changeset script for version management Oct 8, 2025

Copilot finished work on behalf of pelikhan October 8, 2025 05:39

Copilot started work on behalf of pelikhan October 8, 2025 05:51 View session

Copilot AI changed the title ~~Implement changeset script for version management~~ Implement changeset script for version management with dry-run mode Oct 8, 2025

Copilot finished work on behalf of pelikhan October 8, 2025 05:59

pelikhan reviewed Oct 8, 2025

View reviewed changes

Copilot started work on behalf of pelikhan October 8, 2025 12:08 View session

Copilot AI changed the title ~~Implement changeset script for version management with dry-run mode~~ Implement changeset script for version management with dry-run mode and safety checks Oct 8, 2025

Copilot AI requested a review from pelikhan October 8, 2025 12:18

Copilot finished work on behalf of pelikhan October 8, 2025 12:18

Copilot started work on behalf of pelikhan October 8, 2025 12:19 View session

pelikhan reviewed Oct 8, 2025

View reviewed changes

Copilot AI changed the title ~~Implement changeset script for version management with dry-run mode and safety checks~~ Implement changeset script for version management with safety checks Oct 8, 2025

Copilot AI requested a review from pelikhan October 8, 2025 12:27

Copilot finished work on behalf of pelikhan October 8, 2025 12:27

Copilot started work on behalf of pelikhan October 8, 2025 12:27 View session

Copilot AI changed the title ~~Implement changeset script for version management with safety checks~~ Implement internal changeset script for version management with safety checks Oct 8, 2025

Copilot finished work on behalf of pelikhan October 8, 2025 12:31

Copilot started work on behalf of pelikhan October 8, 2025 12:35 View session

Copilot finished work on behalf of pelikhan October 8, 2025 12:41

Copilot started work on behalf of pelikhan October 8, 2025 12:42 View session

Copilot finished work on behalf of pelikhan October 8, 2025 12:44

pelikhan reviewed Oct 8, 2025

View reviewed changes

Copilot started work on behalf of pelikhan October 8, 2025 12:57 View session

Copilot AI requested a review from pelikhan October 8, 2025 13:02

Copilot finished work on behalf of pelikhan October 8, 2025 13:02

pelikhan marked this pull request as ready for review October 8, 2025 13:03

Add changeset for changeset script implementation

eea09b0

pelikhan merged commit 84c5a1a into main Oct 8, 2025

pelikhan deleted the copilot/implement-changesets-cli-integration branch October 8, 2025 13:08

Conversation

Copilot AI commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem Statement

Solution

node scripts/changeset.js version

node scripts/changeset.js release [type]

Safety Checks

Makefile Targets

Implementation Details

Testing

Usage (For Maintainers)

Uh oh!

pelikhan commented Oct 8, 2025

Uh oh!

Copilot AI commented Oct 8, 2025

Uh oh!

pelikhan commented Oct 8, 2025

Uh oh!

Copilot AI commented Oct 8, 2025

Uh oh!

pelikhan left a comment

Choose a reason for hiding this comment

Uh oh!

pelikhan Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Oct 8, 2025

Uh oh!

pelikhan commented Oct 8, 2025

Uh oh!

pelikhan Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

pelikhan Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Oct 8, 2025

Uh oh!

pelikhan commented Oct 8, 2025

Uh oh!

Copilot AI commented Oct 8, 2025

Uh oh!

pelikhan commented Oct 8, 2025

Uh oh!

Copilot AI commented Oct 8, 2025

Uh oh!

pelikhan Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Oct 8, 2025 •

edited

Loading

`node scripts/changeset.js version`

`node scripts/changeset.js release [type]`