fix(extension): address PR review comments and improve implementation
- Fixed InternalError class definition in errorHandler.ts - Updated extension configuration and CI workflows - Improved error handling and type safety - Enhanced build and release automation - Updated documentation and changelogs Addresses review feedback on PR #997
This commit is contained in:
DavidMaliglowka
@@ -1,15 +1,17 @@
|
||||
# VS Code Extension CI/CD Setup
|
||||
|
||||
This document explains the CI/CD setup for the Task Master VS Code extension.
|
||||
This document explains the CI/CD setup for the Task Master VS Code extension using automated changesets.
|
||||
|
||||
## 🔄 Workflows Overview
|
||||
|
||||
### 1. Extension CI (`extension-ci.yml`)
|
||||
|
||||
**Triggers:**
|
||||
- Push to `main` or `next` branches (only when extension files change)
|
||||
- Pull requests to `main` or `next` (only when extension files change)
|
||||
|
||||
**What it does:**
|
||||
|
||||
- ✅ Lints and type-checks the extension code
|
||||
- 🔨 Builds the extension (`pnpm run build`)
|
||||
- 📦 Creates a clean package (`pnpm run package`)
|
||||
@@ -17,23 +19,56 @@ This document explains the CI/CD setup for the Task Master VS Code extension.
|
||||
- 📋 Creates a test VSIX package to verify packaging works
|
||||
- 💾 Uploads build artifacts for inspection
|
||||
|
||||
### 2. Extension Release (`extension-release.yml`)
|
||||
### 2. Version & Publish (`version.yml`)
|
||||
|
||||
**Triggers:**
|
||||
- Push to `main` branch (only when extension files change AND version changes)
|
||||
- Manual trigger with `workflow_dispatch` (with optional force publish)
|
||||
- Push to `main` branch
|
||||
|
||||
**What it does:**
|
||||
- 🔍 Checks if the extension version changed
|
||||
- 🧪 Runs full test suite (lint, typecheck, tests)
|
||||
- 🔨 Builds and packages the extension
|
||||
- 📤 Publishes to VS Code Marketplace
|
||||
- 🌍 Publishes to Open VSX Registry (for VSCodium, Gitpod, etc.)
|
||||
- 🏷️ Creates a GitHub release with the VSIX file
|
||||
- 📊 Uploads release artifacts
|
||||
- 🔍 Detects changeset files for pending releases
|
||||
- 📝 Creates "Version Packages" PR with updated versions and CHANGELOG
|
||||
- 🤖 When Version PR is merged, automatically:
|
||||
- 🔨 Builds and packages the extension
|
||||
- 🏷️ Creates git tags with changeset automation
|
||||
- 📤 Publishes to VS Code Marketplace
|
||||
- 🌍 Publishes to Open VSX Registry
|
||||
- 📊 Updates package versions and CHANGELOG
|
||||
|
||||
## 🚀 Changeset Workflow
|
||||
|
||||
### Creating Changes
|
||||
When making changes to the extension:
|
||||
|
||||
1. **Make your code changes**
|
||||
2. **Create a changeset**:
|
||||
```bash
|
||||
# From project root
|
||||
npx changeset add
|
||||
```
|
||||
3. **Select the extension package**: Choose `taskr-kanban` when prompted
|
||||
4. **Select version bump type**:
|
||||
- `patch`: Bug fixes, minor updates
|
||||
- `minor`: New features, backwards compatible
|
||||
- `major`: Breaking changes
|
||||
5. **Write a summary**: Describe what changed for users
|
||||
6. **Commit changeset file** along with your code changes
|
||||
7. **Push to feature branch** and create PR
|
||||
|
||||
### Automated Publishing Process
|
||||
1. **PR with changeset** gets merged to `main`
|
||||
2. **Version workflow** detects changesets and creates "Version Packages" PR
|
||||
3. **Review and merge** the Version PR
|
||||
4. **Automated publishing** happens immediately:
|
||||
- Extension is built using 3-file packaging system
|
||||
- VSIX package is created and tested
|
||||
- Published to VS Code Marketplace (if `VSCE_PAT` is set)
|
||||
- Published to Open VSX Registry (if `OVSX_PAT` is set)
|
||||
- Git tags are created: `taskr-kanban@1.0.1`
|
||||
- CHANGELOG is updated automatically
|
||||
|
||||
## 🔑 Required Secrets
|
||||
|
||||
To use the release workflow, you need to set up these GitHub repository secrets:
|
||||
To use the automated publishing, you need to set up these GitHub repository secrets:
|
||||
|
||||
### `VSCE_PAT` (VS Code Marketplace Personal Access Token)
|
||||
1. Go to [Azure DevOps](https://dev.azure.com/)
|
||||
@@ -57,45 +92,32 @@ To use the release workflow, you need to set up these GitHub repository secrets:
|
||||
### `GITHUB_TOKEN` (automatically provided)
|
||||
This is automatically available in GitHub Actions - no setup required.
|
||||
|
||||
## 🚀 Publishing Process
|
||||
|
||||
### Automatic Publishing (Recommended)
|
||||
1. **Make changes** to the extension code
|
||||
2. **Update version** in both:
|
||||
- `apps/extension/package.json`
|
||||
- `apps/extension/package.publish.json`
|
||||
3. **Commit and push** to `main` branch
|
||||
4. **CI automatically triggers** and publishes if version changed
|
||||
|
||||
### Manual Publishing
|
||||
1. Go to **Actions** tab in GitHub
|
||||
2. Select **Extension Release** workflow
|
||||
3. Click **Run workflow**
|
||||
4. Check **"Force publish even without version changes"** if needed
|
||||
5. Click **Run workflow**
|
||||
|
||||
## 📋 Version Management
|
||||
|
||||
### Version Sync Checklist
|
||||
When updating the extension version, ensure these fields match in both files:
|
||||
### Changeset-Based Versioning
|
||||
Versions are automatically managed by changesets:
|
||||
|
||||
- **No manual version updates needed** - changesets handle this automatically
|
||||
- **Semantic versioning** is enforced based on changeset types
|
||||
- **Changelog generation** happens automatically
|
||||
- **Git tagging** is handled by the automation
|
||||
|
||||
### Critical Fields Sync
|
||||
The automation ensures these fields stay in sync between `package.json` and `package.publish.json`:
|
||||
|
||||
**`package.json` and `package.publish.json`:**
|
||||
```json
|
||||
{
|
||||
"version": "1.0.2", // ⚠️ MUST MATCH
|
||||
"publisher": "DavidMaliglowka", // ⚠️ MUST MATCH
|
||||
"displayName": "Task Master Kanban", // ⚠️ MUST MATCH
|
||||
"description": "...", // ⚠️ MUST MATCH
|
||||
"engines": { "vscode": "^1.93.0" }, // ⚠️ MUST MATCH
|
||||
"categories": [...], // ⚠️ MUST MATCH
|
||||
"contributes": { ... } // ⚠️ MUST MATCH
|
||||
"version": "1.0.2", // ✅ AUTO-SYNCED
|
||||
"publisher": "DavidMaliglowka", // ⚠️ MUST MATCH MANUALLY
|
||||
"displayName": "taskr: Task Master Kanban", // ⚠️ MUST MATCH MANUALLY
|
||||
"description": "...", // ⚠️ MUST MATCH MANUALLY
|
||||
"engines": { "vscode": "^1.93.0" }, // ⚠️ MUST MATCH MANUALLY
|
||||
"categories": [...], // ⚠️ MUST MATCH MANUALLY
|
||||
"contributes": { ... } // ⚠️ MUST MATCH MANUALLY
|
||||
}
|
||||
```
|
||||
|
||||
### Version Detection Logic
|
||||
The release workflow only publishes when:
|
||||
- Extension files changed in the push, AND
|
||||
- Version field changed in `package.json` or `package.publish.json`
|
||||
**Note**: Only `version` is automatically synced. Other fields must be manually kept in sync.
|
||||
|
||||
## 🔍 Monitoring Builds
|
||||
|
||||
@@ -104,44 +126,61 @@ The release workflow only publishes when:
|
||||
- **Red ❌**: Build/test failures - check logs for details
|
||||
- **Yellow 🟡**: Partial success - some jobs may have warnings
|
||||
|
||||
### Version PR Status
|
||||
- **Version PR Created**: Changesets detected, review and merge to publish
|
||||
- **No Version PR**: No changesets found, no releases pending
|
||||
- **Version PR Merged**: Automated publishing triggered
|
||||
|
||||
### Release Status
|
||||
- **Published 🎉**: Extension live on VS Code Marketplace
|
||||
- **Skipped ℹ️**: No version changes detected
|
||||
- **Published 🎉**: Extension live on VS Code Marketplace and Open VSX
|
||||
- **Skipped ℹ️**: No changesets found, no release needed
|
||||
- **Failed ❌**: Check logs - often missing secrets or build issues
|
||||
|
||||
### Artifacts
|
||||
Both workflows upload artifacts that you can download:
|
||||
Workflows upload artifacts that you can download:
|
||||
- **CI**: Test results, built files, and VSIX package
|
||||
- **Release**: Final VSIX package and build artifacts (90-day retention)
|
||||
- **Version**: Final VSIX package and published extension
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"VSCE_PAT is not set" Error**
|
||||
#### No Version PR Created
|
||||
- **Check**: Changeset files exist in `.changeset/` directory
|
||||
- **Check**: Changeset refers to `taskr-kanban` package name
|
||||
- **Check**: Changes were pushed to `main` branch
|
||||
- **Solution**: Create changeset with `npx changeset add`
|
||||
|
||||
#### Version PR Not Publishing
|
||||
- **Check**: Version PR was actually merged (not just closed)
|
||||
- **Check**: Required secrets (`VSCE_PAT`, `OVSX_PAT`) are set
|
||||
- **Check**: No build failures in workflow logs
|
||||
- **Solution**: Re-run workflow or check secret configuration
|
||||
|
||||
#### `VSCE_PAT` is not set Error
|
||||
- Ensure `VSCE_PAT` secret is added to repository
|
||||
- Check token hasn't expired
|
||||
- Verify token has Marketplace > Manage permissions
|
||||
- Verify token has Marketplace → Manage permissions
|
||||
|
||||
**"OVSX_PAT is not set" Error**
|
||||
#### `OVSX_PAT` is not set Error
|
||||
- Ensure `OVSX_PAT` secret is added to repository
|
||||
- Check token hasn't expired
|
||||
- Verify you're signed in to Open VSX Registry with GitHub
|
||||
|
||||
**"Version not changed" Skipped Release**
|
||||
- Update version in both `package.json` AND `package.publish.json`
|
||||
- Ensure files are committed and pushed
|
||||
- Use manual trigger with force publish if needed
|
||||
|
||||
**Build Failures**
|
||||
#### Build Failures
|
||||
- Check extension code compiles locally: `cd apps/extension && pnpm run build`
|
||||
- Verify tests pass locally: `pnpm run test`
|
||||
- Check for TypeScript errors: `pnpm run check-types`
|
||||
|
||||
**Packaging Failures**
|
||||
#### Packaging Failures
|
||||
- Ensure clean package builds: `pnpm run package`
|
||||
- Check vsix-build structure is correct
|
||||
- Verify package.publish.json has correct fields
|
||||
- Verify `package.publish.json` has correct `repository` field
|
||||
|
||||
#### Changeset Issues
|
||||
- **Wrong package name**: Ensure changeset refers to `taskr-kanban`
|
||||
- **Invalid format**: Check changeset markdown format is correct
|
||||
- **Merge conflicts**: Resolve any conflicts in changeset files
|
||||
|
||||
## 📁 File Structure Impact
|
||||
|
||||
@@ -149,11 +188,22 @@ The CI workflows respect the 3-file packaging system:
|
||||
- **Development**: Uses `package.json` for dependencies and scripts
|
||||
- **Release**: Uses `package.publish.json` for clean marketplace package
|
||||
- **Build**: Uses `package.mjs` to create `vsix-build/` for final packaging
|
||||
- **Changesets**: Automatically manage versions across the system
|
||||
|
||||
This ensures clean, conflict-free publishing to both VS Code Marketplace and Open VSX Registry! 🚀
|
||||
|
||||
## 🌍 **Dual Registry Publishing**
|
||||
## 🌍 Dual Registry Publishing
|
||||
|
||||
Your extension will be automatically published to both:
|
||||
- **VS Code Marketplace** - For official VS Code users
|
||||
- **Open VSX Registry** - For Cursor, Windsurf, VSCodium, Gitpod, Eclipse Theia, and other compatible editors
|
||||
- **Open VSX Registry** - For Cursor, Windsurf, VSCodium, Gitpod, Eclipse Theia, and other compatible editors
|
||||
|
||||
## 🎯 Benefits of Changeset Automation
|
||||
|
||||
- ✅ **Automated versioning**: No manual version bumps needed
|
||||
- ✅ **Generated changelogs**: Automatic, accurate release notes
|
||||
- ✅ **Semantic versioning**: Enforced through changeset types
|
||||
- ✅ **Git tagging**: Proper tags for extension releases
|
||||
- ✅ **Conflict prevention**: Clear separation of extension vs. main package versions
|
||||
- ✅ **Review process**: Version changes are reviewable via PR
|
||||
- ✅ **Rollback capability**: Easy to revert if issues arise
|
||||
|
||||
This ensures clean, predictable, and fully automated publishing to both registries! 🚀
|
||||
@@ -138,6 +138,65 @@ When updating extension metadata, ensure these fields match between `package.jso
|
||||
}
|
||||
```
|
||||
|
||||
## 🤖 Automated Release Process
|
||||
|
||||
### Changesets Workflow
|
||||
This extension uses [Changesets](https://github.com/changesets/changesets) for automated version management and publishing.
|
||||
|
||||
#### Adding Changes
|
||||
When making changes to the extension:
|
||||
|
||||
1. **Make your code changes**
|
||||
2. **Create a changeset**:
|
||||
```bash
|
||||
# From project root
|
||||
npx changeset add
|
||||
```
|
||||
3. **Select the extension package**: Choose `taskr-kanban` when prompted
|
||||
4. **Select version bump type**:
|
||||
- `patch`: Bug fixes, minor updates
|
||||
- `minor`: New features, backwards compatible
|
||||
- `major`: Breaking changes
|
||||
5. **Write a summary**: Describe what changed for users
|
||||
|
||||
#### Automated Publishing
|
||||
The automation workflow runs on pushes to `main`:
|
||||
|
||||
1. **Version Workflow** (`.github/workflows/version.yml`):
|
||||
- Detects when changesets exist
|
||||
- Creates a "Version Packages" PR with updated versions and CHANGELOG
|
||||
- When the PR is merged, automatically publishes the extension
|
||||
|
||||
2. **Release Process** (`scripts/release.sh`):
|
||||
- Builds the extension using the 3-file packaging system
|
||||
- Creates VSIX package
|
||||
- Publishes to VS Code Marketplace (if `VSCE_PAT` is set)
|
||||
- Publishes to Open VSX Registry (if `OVSX_PAT` is set)
|
||||
- Creates git tags for the extension version
|
||||
|
||||
#### Required Secrets
|
||||
For automated publishing, these secrets must be set in the repository:
|
||||
|
||||
- `VSCE_PAT`: Personal Access Token for VS Code Marketplace
|
||||
- `OVSX_PAT`: Personal Access Token for Open VSX Registry
|
||||
- `GITHUB_TOKEN`: Automatically provided by GitHub Actions
|
||||
|
||||
#### Manual Release
|
||||
If needed, you can manually trigger a release:
|
||||
|
||||
```bash
|
||||
# From project root
|
||||
./scripts/release.sh
|
||||
```
|
||||
|
||||
### Extension Tagging
|
||||
The extension uses a separate tagging strategy from the main package:
|
||||
|
||||
- **Extension tags**: `taskr-kanban@1.0.1`
|
||||
- **Main package tags**: `task-master-ai@2.1.0`
|
||||
|
||||
This allows independent versioning and prevents conflicts in the monorepo.
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Dependency Conflicts
|
||||
@@ -155,14 +214,32 @@ When updating extension metadata, ensure these fields match between `package.jso
|
||||
**Problem**: Extension works locally but fails when packaged
|
||||
**Check**: Ensure critical fields are synced between package files
|
||||
|
||||
### Changeset Issues
|
||||
**Problem**: Version workflow not triggering
|
||||
**Check**:
|
||||
1. Changeset files exist in `.changeset/`
|
||||
2. Package name in changeset matches `package.publish.json`
|
||||
3. Changes are pushed to `main` branch
|
||||
|
||||
**Problem**: Publishing fails
|
||||
**Check**:
|
||||
1. Required secrets are set in repository settings
|
||||
2. `package.publish.json` has correct repository URL
|
||||
3. Build process completes successfully
|
||||
|
||||
## 📝 Version Release Checklist
|
||||
|
||||
1. **Update version** in both `package.json` and `package.publish.json`
|
||||
2. **Update CHANGELOG.md** with new features/fixes
|
||||
### Manual Releases
|
||||
1. **Create changeset**: `npx changeset add`
|
||||
2. **Update critical fields** in both `package.json` and `package.publish.json`
|
||||
3. **Test locally** with `F5` in VS Code
|
||||
4. **Build clean package**: `pnpm run package`
|
||||
5. **Test packaged extension**: Install `.vsix` file
|
||||
6. **Publish**: Upload to marketplace or distribute `.vsix`
|
||||
4. **Commit and push** to trigger automated workflow
|
||||
|
||||
### Automated Releases (Recommended)
|
||||
1. **Create changeset**: `npx changeset add`
|
||||
2. **Push to feature branch** and create PR
|
||||
3. **Merge PR** - this triggers version PR creation
|
||||
4. **Review and merge version PR** - this triggers automated publishing
|
||||
|
||||
## 🎯 Why This System?
|
||||
|
||||
@@ -171,7 +248,9 @@ When updating extension metadata, ensure these fields match between `package.jso
|
||||
- **Faster packaging**: No dependency resolution during `vsce package`
|
||||
- **Maintainable**: Clear separation of dev vs. production configs
|
||||
- **Reliable**: Consistent, conflict-free packaging process
|
||||
- **Automated**: Changesets handle versioning and publishing automatically
|
||||
- **Traceable**: Clear changelog and git tags for every release
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Always use `pnpm run package` → `cd vsix-build` → `vsce package --no-dependencies` for production builds! 🚀
|
||||
**Remember**: Always use `npx changeset add` for changes, then push to trigger automated releases! 🚀
|
||||
|
||||
Reference in New Issue
Block a user