Skip to content

PUBLISHING_GUIDE.md

Latest commit

 

History

History
275 lines (192 loc) · 7.02 KB

PUBLISHING_GUIDE.md

File metadata and controls

275 lines (192 loc) · 7.02 KB
Raw

Publishing CodeGuard to VSCode Marketplace

This guide walks you through publishing CodeGuard to the Visual Studio Code Marketplace.

Prerequisites

Before publishing, you need:

  1. Microsoft Account - Create one at https://account.microsoft.com if you don't have one
  2. Azure DevOps Organization - For managing your publisher account
  3. Personal Access Token (PAT) - For authentication
  4. vsce CLI Tool - VSCode Extension Manager

Step 1: Install vsce (VSCode Extension Manager)

npm install -g @vscode/vsce

Verify installation:

vsce --version

Step 2: Create Azure DevOps Organization

  1. Go to https://dev.azure.com
  2. Sign in with your Microsoft account
  3. Click "Create new organization"
  4. Choose a name (e.g., "codeguard-publisher")
  5. Complete the setup

Step 3: Create Personal Access Token (PAT)

  1. In Azure DevOps, click your profile icon (top right)
  2. Select "Personal access tokens"
  3. Click "+ New Token"
  4. Configure the token:
    • Name: "VSCode Marketplace Publisher"
    • Organization: Select your organization
    • Expiration: Choose duration (90 days, 1 year, or custom)
    • Scopes: Select "Custom defined"
    • Check "Marketplace" > "Manage" (this is critical!)
  5. Click "Create"
  6. IMPORTANT: Copy the token immediately - you won't see it again!
  7. Save it securely (e.g., password manager)

Step 4: Create Publisher Account

  1. Go to https://marketplace.visualstudio.com/manage
  2. Sign in with your Microsoft account
  3. Click "Create publisher"
  4. Fill in the form:
    • Publisher ID: Unique identifier (e.g., "lekhanpro" or "codeguard-team")
      • Must be lowercase, alphanumeric, hyphens allowed
      • Cannot be changed later!
    • Display Name: "CodeGuard" or your preferred name
    • Email: Your contact email
    • Description: Brief description of your publisher profile
  5. Click "Create"

Step 5: Update package.json

Update the publisher field in package.json with your Publisher ID:

{
  "publisher": "your-publisher-id",
  "repository": {
    "type": "git",
    "url": "https://github.com/lekhanpro/CodeGuard.git"
  },
  "bugs": {
    "url": "https://github.com/lekhanpro/CodeGuard/issues"
  },
  "homepage": "https://github.com/lekhanpro/CodeGuard#readme",
  "icon": "icon.png"
}

Step 6: Add Extension Icon (Optional but Recommended)

Create a 128x128 PNG icon named icon.png in the root directory. This will be displayed in the marketplace.

If you don't have an icon yet, you can skip this and add it later.

Step 7: Login to vsce

vsce login your-publisher-id

When prompted, paste your Personal Access Token (PAT).

Step 8: Package the Extension

Before publishing, test the package locally:

npm run compile
vsce package

This creates a .vsix file (e.g., codeguard-0.1.0.vsix).

Test the Package Locally

Install the packaged extension in VSCode:

code --install-extension codeguard-0.1.0.vsix

Test it thoroughly to ensure everything works.

Step 9: Publish to Marketplace

Once you're satisfied with testing:

vsce publish

Or publish with a specific version:

vsce publish 0.1.0

Or publish and increment version automatically:

vsce publish patch  # 0.1.0 -> 0.1.1
vsce publish minor  # 0.1.0 -> 0.2.0
vsce publish major  # 0.1.0 -> 1.0.0

Step 10: Verify Publication

  1. Go to https://marketplace.visualstudio.com/manage
  2. You should see your extension listed
  3. Click on it to view details
  4. The extension will be available at: 
    https://marketplace.visualstudio.com/items?itemName=your-publisher-id.codeguard

Step 11: Install from Marketplace

After publication (may take a few minutes to appear):

  1. Open VSCode
  2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
  3. Search for "CodeGuard"
  4. Click Install

Publishing Updates

When you have updates:

  1. Update version in package.json
  2. Update CHANGELOG.md with changes
  3. Commit and push to GitHub
  4. Run vsce publish again

Or use automatic versioning:

# For bug fixes
vsce publish patch

# For new features
vsce publish minor

# For breaking changes
vsce publish major

Troubleshooting

Error: "Publisher not found"

Error: "Personal Access Token is invalid"

  • Create a new PAT with "Marketplace > Manage" scope
  • Run vsce login your-publisher-id again

Error: "Extension validation failed"

  • Check that all required fields in package.json are filled
  • Ensure README.md exists and has content
  • Verify LICENSE file exists

Error: "Icon not found"

  • Either add an icon.png file (128x128)
  • Or remove the "icon" field from package.json

Best Practices

  1. Version Control: Always commit and push to GitHub before publishing
  2. Testing: Test the packaged .vsix file before publishing
  3. Changelog: Keep CHANGELOG.md updated with each release
  4. Semantic Versioning: Follow semver (MAJOR.MINOR.PATCH)
  5. Documentation: Keep README.md comprehensive and up-to-date
  6. Security: Never commit your PAT to version control

Marketplace Features

After publishing, you can:

  1. View Statistics: See download counts, ratings, and reviews
  2. Respond to Reviews: Engage with users
  3. Update Metadata: Change description, categories, etc.
  4. Unpublish: Remove extension if needed (use carefully!)

Marketing Your Extension

  1. GitHub README: Add marketplace badge:

    [![VSCode Marketplace](https://img.shields.io/vscode-marketplace/v/your-publisher-id.codeguard.svg)](https://marketplace.visualstudio.com/items?itemName=your-publisher-id.codeguard)

  2. Social Media: Share on Twitter, LinkedIn, Reddit (r/vscode)

  3. Blog Post: Write about your extension's features

  4. Documentation: Create comprehensive docs on GitHub wiki

Useful Commands

# Login to publisher account
vsce login your-publisher-id

# Package extension (creates .vsix)
vsce package

# Publish extension
vsce publish

# Publish with version bump
vsce publish patch|minor|major

# Show extension info
vsce show your-publisher-id.codeguard

# Unpublish extension (careful!)
vsce unpublish your-publisher-id.codeguard

# List all versions
vsce ls your-publisher-id.codeguard

Resources

Support

If you encounter issues:

  1. Check the VSCode Extension API docs
  2. Visit VSCode Extension Development Discord
  3. Ask on Stack Overflow

Ready to publish? Follow the steps above and your extension will be live on the VSCode Marketplace!