claude-task-master/apps/extension/docs/extension-CI-setup.md

# VS Code Extension CI/CD Setup

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 (`npm run build`)
- 📦 Creates a clean package (`npm run package`)
- 🧪 Runs tests with VS Code test framework
- 📋 Creates a test VSIX package to verify packaging works
- 💾 Uploads build artifacts for inspection

### 2. Version & Publish (`version.yml`)

**Triggers:**
- Push to `main` branch

**What it does:**
- 🔍 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 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/)
2. Sign in with your Microsoft account
3. Create a Personal Access Token:
   - **Name**: VS Code Extension Publishing
   - **Organization**: All accessible organizations
   - **Expiration**: Custom (recommend 1 year)
   - **Scopes**: Custom defined → **Marketplace** → **Manage**
4. Copy the token and add it to GitHub Secrets as `VSCE_PAT`

### `OVSX_PAT` (Open VSX Registry Personal Access Token)
1. Go to [Open VSX Registry](https://open-vsx.org/)
2. Sign in with your GitHub account
3. Go to your [User Settings](https://open-vsx.org/user-settings/tokens)
4. Create a new Access Token:
   - **Description**: VS Code Extension Publishing
   - **Scopes**: Leave default (full access)
5. Copy the token and add it to GitHub Secrets as `OVSX_PAT`

### `GITHUB_TOKEN` (automatically provided)
This is automatically available in GitHub Actions - no setup required.

## 📋 Version Management

### 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`:

```json
{
  "version": "1.0.2",                    // ✅ AUTO-SYNCED
  "publisher": "Hamster",        // ⚠️ 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
}
```

**Note**: Only `version` is automatically synced. Other fields must be manually kept in sync.

## 🔍 Monitoring Builds

### CI Status

- **Green ✅**: Extension builds and tests successfully
- **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 and Open VSX
- **Skipped ℹ️**: No changesets found, no release needed
- **Failed ❌**: Check logs - often missing secrets or build issues

### Artifacts

Workflows upload artifacts that you can download:

- **CI**: Test results, built files, and VSIX package
- **Version**: Final VSIX package and published extension

## 🛠️ Troubleshooting

### Common Issues

#### 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

#### `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

#### Build Failures

- Check extension code compiles locally: `cd apps/extension && npm run build`
- Verify tests pass locally: `npm run test`
- Check for TypeScript errors: `npm run typecheck`

#### Packaging Failures

- Ensure clean package builds: `npm run package`
- Check vsix-build structure is correct
- 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

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

## 🌍 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

## 🎯 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! 🚀