# VS Code Marketplace Publishing Guide

**Last Updated:** March 10, 2026  
**Extension:** Acurity Architect Editor (Unofficial)  
**Current Version:** 0.0.6

---

## Overview

This guide walks through the complete process of publishing the Acurity extension to the Visual Studio Code Marketplace.

## Prerequisites

### 1. Microsoft/Azure Account Setup

**Required Accounts:**
- Microsoft Account (personal or work)
- Azure DevOps organization

**Steps:**
1. **Create Azure DevOps Organization**
   - Go to https://dev.azure.com
   - Sign in with your Microsoft account
   - Click "New organization" if you don't have one
   - Choose a name (e.g., "jibbius-extensions")

2. **Create Personal Access Token (PAT)**
   - Go to https://dev.azure.com/{your-org}
   - Click User Settings (top right) → Personal access tokens
   - Click "+ New Token"
   - Configure:
     - **Name:** "VS Code Marketplace Publishing"
     - **Organization:** All accessible organizations
     - **Expiration:** 90 days (or custom)
     - **Scopes:** Select "Marketplace" → Check "Manage"
   - Click "Create" and **SAVE THE TOKEN** (you can't see it again!)

3. **Create Publisher Account**
   - Go to https://marketplace.visualstudio.com/manage
   - Sign in with the same Microsoft account
   - Click "Create publisher"
   - Fill in:
     - **Publisher ID:** `jibbius` (must match `package.json`)
     - **Display Name:** Your name or organization
     - **Description:** Optional description of your published extensions
   - Click "Create"

---

## Package.json Requirements

### ✅ Current Status

**Already configured:**
- ✅ `name`: "acurity"
- ✅ `publisher`: "jibbius"
- ✅ `displayName`: "Acurity Architect Editor (Unofficial)"
- ✅ `description`: Clear and concise
- ✅ `version`: "0.0.6"
- ✅ `engines.vscode`: "^1.33.0"
- ✅ `categories`: ["Programming Languages"]
- ✅ `main`: "./extension.js"
- ✅ `activationEvents`: Properly configured
- ✅ `contributes`: Complete configuration

### ❌ Missing (Required)

Add these fields to `package.json`:

```json
{
  "repository": {
    "type": "git",
    "url": "https://github.com/jibbius/acurity-vscode-extension"
  },
  "bugs": {
    "url": "https://github.com/jibbius/acurity-vscode-extension/issues"
  },
  "homepage": "https://github.com/jibbius/acurity-vscode-extension#readme",
  "license": "MIT",
  "icon": "images/icon.png",
  "keywords": [
    "acurity",
    "architect",
    "qmv",
    "syntax highlighting",
    "language support"
  ]
}
```

### ⚠️ Recommended (Optional but highly recommended)

```json
{
  "galleryBanner": {
    "color": "#1e1e1e",
    "theme": "dark"
  },
  "qna": "marketplace",
  "badges": [
    {
      "url": "https://img.shields.io/visual-studio-marketplace/v/jibbius.acurity",
      "href": "https://marketplace.visualstudio.com/items?itemName=jibbius.acurity",
      "description": "VS Code Marketplace Version"
    }
  ]
}
```

---

## Required Assets

### 1. Extension Icon (REQUIRED)

**Specifications:**
- **Size:** 128x128 pixels (PNG format)
- **Location:** `images/icon.png` (create `images/` folder)
- **Design:** Should represent Acurity or general language/code concept
- **Background:** Can be transparent or solid color

**Quick Creation Options:**
- Use a free icon generator (e.g., https://www.logomaker.com/)
- Create simple geometric design in any graphic editor
- Use a code/document icon from free icon sets (Font Awesome, Heroicons)

**Example simple icon creation:**
```bash
# Create images folder
mkdir images

# Option 1: Download a free icon from Heroicons or similar
# Option 2: Create a simple colored square with "A" text
# Option 3: Use an online generator
```

### 2. Repository Screenshots (OPTIONAL but recommended)

Add to repository:
- **Screenshot 1:** Syntax highlighting example
- **Screenshot 2:** Diagnostics in action
- **Screenshot 3:** Quick fixes demo

Reference in README with:
```markdown
![Syntax Highlighting](images/screenshot-syntax.png)
![Diagnostics](images/screenshot-diagnostics.png)
```

---

## Repository Setup

### 1. Create GitHub Repository

**If not already created:**

```bash
# Create new repo on GitHub first, then:
git init
git add .
git commit -m "Initial commit - v0.0.6"
git branch -M main
git remote add origin https://github.com/jibbius/acurity-vscode-extension.git
git push -u origin main
```

### 2. Add Recommended Files

**Create `.github/ISSUE_TEMPLATE/bug_report.md`:**
```markdown
---
name: Bug Report
about: Report an issue with the extension
---

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Open file '...'
2. Type '...'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
- VS Code Version: [e.g. 1.85.0]
- Extension Version: [e.g. 0.0.6]
- OS: [e.g. Windows 11]

**Additional context**
Any other context about the problem.
```

**Create `.github/ISSUE_TEMPLATE/feature_request.md`:**
```markdown
---
name: Feature Request
about: Suggest an enhancement
---

**Is your feature request related to a problem?**
A clear description of the problem.

**Describe the solution you'd like**
What you want to happen.

**Describe alternatives you've considered**
Other solutions you've thought about.

**Additional context**
Any other context or screenshots.
```

### 3. Add Tags/Releases

After first publish:
```bash
git tag v0.0.6
git push origin v0.0.6
```

---

## Publishing Steps

### Method 1: Using vsce CLI (Recommended)

**1. Install vsce globally:**
```bash
npm install -g @vscode/vsce
```

**2. Login to publisher:**
```bash
vsce login jibbius
# Enter your Personal Access Token (PAT) when prompted
```

**3. Package and publish:**
```bash
# Option A: Package only (for manual upload)
vsce package

# Option B: Package and publish directly
vsce publish
```

**For subsequent releases:**
```bash
# Patch version (0.0.6 → 0.0.7)
vsce publish patch

# Minor version (0.0.6 → 0.1.0)
vsce publish minor

# Major version (0.0.6 → 1.0.0)
vsce publish major
```

### Method 2: Manual Upload

**1. Package the extension:**
```bash
npm run package:vsix
# Creates: dist/acurity.vsix
```

**2. Upload manually:**
- Go to https://marketplace.visualstudio.com/manage/publishers/jibbius
- Click "New extension" → "Visual Studio Code"
- Drag and drop `dist/acurity.vsix`
- Fill in any additional marketplace metadata
- Click "Upload"

---

## Pre-Publication Checklist

Before publishing, verify:

### Package Quality
- [ ] Run `npm run package:vsix` - Builds successfully
- [ ] Verify package size is reasonable (< 5 MB ideally)
- [ ] Package contains only necessary files (check `.vscodeignore`)
- [ ] All tests pass: `npm run test:syntax`

### Metadata
- [ ] `package.json` has all required fields (repository, bugs, homepage, icon, keywords)
- [ ] `README.md` is comprehensive and well-formatted
- [ ] `CHANGELOG.md` has release notes for current version
- [ ] `LICENSE` file exists (MIT license included)
- [ ] Extension icon exists at `images/icon.png` (128x128 PNG)

### Functionality
- [ ] Install VSIX locally and test all features
- [ ] Syntax highlighting works on `.txt` files
- [ ] Diagnostics run and display correctly
- [ ] Quick fixes work as expected
- [ ] Settings UI renders properly
- [ ] No console errors in Developer Tools

### Documentation
- [ ] README screenshots (if available)
- [ ] GitHub repository is public
- [ ] Issue templates are set up
- [ ] Contributing guidelines exist (optional)

### Legal/Compliance
- [ ] "Unofficial" disclaimer is prominent
- [ ] No trademarked content without permission
- [ ] No proprietary code included
- [ ] License is appropriate for all dependencies

---

## Post-Publication

### 1. Verify Publication

**Check marketplace page:**
- Go to https://marketplace.visualstudio.com/items?itemName=jibbius.acurity
- Verify all information displays correctly
- Test "Install" button works
- Review screenshots and README rendering

### 2. Install from Marketplace

**Test fresh install:**
```
1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search "Acurity Architect"
4. Click Install
5. Test all features
```

### 3. Create GitHub Release

```bash
# Tag the release
git tag -a v0.0.6 -m "Release v0.0.6 - First marketplace publication"
git push origin v0.0.6

# On GitHub:
# Go to Releases → Draft new release
# Select tag v0.0.6
# Copy CHANGELOG content
# Attach dist/acurity.vsix as asset
# Publish release
```

### 4. Share the Release

- Tweet/social media announcement
- Post in relevant communities (if applicable)
- Update any project documentation with install link

---

## Updating Published Extension

### For Bug Fixes (Patch)

```bash
# 1. Make code changes
# 2. Update CHANGELOG.md
# 3. Bump version
npm version patch  # 0.0.6 → 0.0.7

# 4. Publish
vsce publish patch

# 5. Commit and tag
git add .
git commit -m "Release v0.0.7 - Bug fixes"
git tag v0.0.7
git push origin main --tags
```

### For New Features (Minor)

```bash
npm version minor  # 0.0.7 → 0.1.0
vsce publish minor
git add .
git commit -m "Release v0.1.0 - New features"
git tag v0.1.0
git push origin main --tags
```

### For Breaking Changes (Major)

```bash
npm version major  # 0.1.0 → 1.0.0
vsce publish major
git add .
git commit -m "Release v1.0.0 - Major release"
git tag v1.0.0
git push origin main --tags
```

---

## Troubleshooting

### "ERROR Missing publisher name"

**Problem:** package.json is missing `publisher` field.

**Solution:** Add `"publisher": "jibbius"` to package.json

---

### "ERROR Missing repository"

**Problem:** package.json is missing `repository` field.

**Solution:** Add repository field or use `--allow-missing-repository` flag:
```bash
vsce package --allow-missing-repository
```

---

### "ERROR Cannot find icon"

**Problem:** package.json references an icon file that doesn't exist.

**Solution:** 
- Create the icon at the specified path
- Or remove `"icon"` field from package.json temporarily

---

### "ERROR Personal access token is invalid"

**Problem:** PAT has expired or has wrong scopes.

**Solution:**
1. Create new PAT with "Marketplace (Manage)" scope
2. Run `vsce login jibbius` again
3. Enter new token

---

### "Extension fails to activate after install"

**Problem:** Extension activation errors.

**Solution:**
1. Check Developer Tools console (Help → Toggle Developer Tools)
2. Look for errors in Output panel (View → Output → Select "Acurity")
3. Verify `main` field in package.json points to correct file
4. Verify all dependencies are bundled

---

## Marketplace Metrics

After publication, monitor:

- **Install count:** https://marketplace.visualstudio.com/manage/publishers/jibbius
- **Ratings and reviews:** Check marketplace page
- **Issues:** Monitor GitHub issues
- **Questions:** Check marketplace Q&A section

---

## Unpublishing (If Needed)

**To remove extension from marketplace:**

```bash
vsce unpublish jibbius.acurity
```

**⚠️ Warning:** Unpublishing removes it for all users. Consider deprecating instead if users depend on it.

---

## Summary: Quick Publication Steps

For someone who has everything ready:

1. **Setup** (one-time):
   ```bash
   npm install -g @vscode/vsce
   vsce login jibbius
   ```

2. **Add missing fields to package.json**:
   - repository, bugs, homepage, icon, keywords

3. **Create 128x128 icon**:
   - Save as `images/icon.png`

4. **Publish**:
   ```bash
   vsce publish
   ```

5. **Verify** on marketplace and test install

Done! 🚀

---

## Resources

- **VS Code Publishing Guide:** https://code.visualstudio.com/api/working-with-extensions/publishing-extension
- **vsce Documentation:** https://github.com/microsoft/vscode-vsce
- **Marketplace Management:** https://marketplace.visualstudio.com/manage
- **Azure DevOps:** https://dev.azure.com
- **Extension Guidelines:** https://code.visualstudio.com/api/references/extension-guidelines

---

**Status:** Ready for publication after completing:
1. Add repository fields to package.json
2. Create extension icon (128x128 PNG)
3. Setup Azure DevOps & publisher account
4. Run `vsce publish`
