====== WvdS VSCode Packaging ======

The Packaging extension creates VSIX packages and enables publishing to the Visual Studio Marketplace.

===== Function and Purpose =====

The Packaging extension provides:

  * **VSIX Creation** - Packages for VS Code extensions
  * **Version Management** - Automatic version number management
  * **Multi-Extension Support** - Package multiple extensions simultaneously
  * **Marketplace Publishing** - Direct publishing

===== Commands =====

^ Command ^ Description ^
| ''WVDS: Create VSIX Package'' | Creates a VSIX package |
| ''WVDS: Publish Package'' | Publishes to the VS Marketplace |

===== Creating VSIX Packages =====

==== Prerequisites ====

  * Node.js installed
  * ''vsce'' tool available: <code bash>
npm install -g @vscode/vsce
</code>

==== Workflow ====

  - Ensure the project compiles
  - ''Ctrl+Shift+P'' -> ''WVDS: Create VSIX Package''
  - Select the extension (if multiple exist)
  - The package is created in ''binaries/dist/''

==== Output ====

<code>
binaries/dist/
  wvds-vscode-core-0.1.0.vsix
  wvds-vscode-build-0.1.0.vsix
  ...
</code>

===== Version Management =====

==== Semantic Versioning ====

The suite uses Semantic Versioning (SemVer):

<code>
MAJOR.MINOR.PATCH
  1.0.0
</code>

^ Part ^ Increment When ^
| MAJOR | Breaking changes, incompatible API changes |
| MINOR | New features, backward compatible |
| PATCH | Bug fixes, no feature changes |

==== Automatic Increment ====

When packaging, the version can be automatically incremented:
  - Select "Increment Version" in the dialog
  - Choose the part to increment (MAJOR, MINOR, PATCH)
  - The package.json is updated

==== Pre-Release Versions ====

For beta releases:
<code>
1.0.0-beta.1
1.0.0-rc.1
</code>

===== Multi-Extension Packaging =====

The suite consists of multiple extensions that can be packaged together.

==== Extension Pack ====

An extension pack bundles multiple extensions:

<code json>
{
  "name": "wvds-fpc-rad-suite",
  "displayName": "WvdS FPC RAD Suite",
  "extensionPack": [
    "wvds.wvds-vscode-core",
    "wvds.wvds-vscode-build",
    "wvds.wvds-vscode-projects",
    "wvds.wvds-vscode-ui-designer",
    "wvds.wvds-vscode-ui-meta",
    "wvds.wvds-vscode-ui-preview",
    "wvds.wvds-vscode-packaging"
  ]
}
</code>

==== Batch Packaging ====

Package all extensions at once:
  - ''WVDS: Create VSIX Package''
  - Select "All Extensions"
  - All packages are created

===== Marketplace Publishing =====

==== Prerequisites ====

  - **Azure DevOps Organization** - For publisher account
  - **Personal Access Token (PAT)** - With Marketplace permissions
  - **Publisher ID** - Registered at marketplace.visualstudio.com

==== Creating a Publisher ====

  - Visit [[https://marketplace.visualstudio.com/manage|marketplace.visualstudio.com/manage]]
  - Create a publisher
  - Note the Publisher ID

==== Creating a PAT ====

  - Visit [[https://dev.azure.com|dev.azure.com]]
  - User Settings -> Personal Access Tokens
  - Create a token with "Marketplace (Publish)" scope

==== Publishing ====

  - ''WVDS: Publish Package''
  - Enter the PAT (stored securely)
  - The extension is uploaded

<note warning>Do not publish extensions containing sensitive data!</note>

===== Pre-Publish Checks =====

Before publishing, the following are automatically checked:

^ Check ^ Description ^
| Version | Must be higher than published version |
| README | Must exist and not be empty |
| CHANGELOG | Must contain changes for current version |
| License | Must be specified |
| Icon | Recommended (128x128 PNG) |
| Repository | Recommended (link to source code) |

===== package.json Requirements =====

For Marketplace publishing:

<code json>
{
  "name": "wvds-vscode-core",
  "displayName": "WvdS VSCode Core",
  "description": "Central infrastructure for WvdS FPC RAD Studio",
  "version": "0.1.0",
  "publisher": "wvds",
  "license": "MIT",
  "icon": "images/icon.png",
  "repository": {
    "type": "git",
    "url": "https://github.com/ArmandoFilho/WvdS.FPC"
  },
  "engines": {
    "vscode": "^1.85.0"
  },
  "categories": ["Other"],
  "keywords": ["pascal", "fpc", "free pascal"]
}
</code>

===== Local Installation =====

For testing before publishing:

<code bash>
code --install-extension binaries/dist/wvds-vscode-core-0.1.0.vsix
</code>

Or in VS Code:
  - Extensions -> "..." -> "Install from VSIX..."
  - Select the VSIX file

===== Troubleshooting =====

==== "vsce not found" ====

**Cause:** vsce not installed.

**Solution:**
<code bash>
npm install -g @vscode/vsce
</code>

==== "Invalid publisher" ====

**Cause:** Publisher ID in package.json does not match registered publisher.

**Solution:**
  - Check the Publisher ID in package.json
  - Ensure the publisher is registered

==== "Version already exists" ====

**Cause:** This version was already published.

**Solution:**
  - Increment the version number
  - Use the increment function

==== "PAT expired" ====

**Cause:** Personal Access Token expired.

**Solution:**
  - Create a new PAT
  - Enter it on the next publish

===== Technical Details =====

^ Property ^ Value ^
| Extension ID | wvds.wvds-vscode-packaging |
| Activation | onCommand:wvds.packaging.create |
| Dependencies | wvds-vscode-core, wvds-vscode-build |
| Min. VS Code | 1.85.0 |

===== See Also =====

  * [[.:build|Build Extension - Compilation]]
  * [[.:core|Core Extension - Toolchain]]
  * [[https://code.visualstudio.com/api/working-with-extensions/publishing-extension|VS Code Publishing Docs]]