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

La Packaging Extension crea pacchetti VSIX e permette la pubblicazione su Visual Studio Marketplace.

===== Funzione e scopo =====

La Packaging Extension offre:

  * **Creazione VSIX** - Pacchetti per estensioni VS Code
  * **Gestione versioni** - Gestione automatica dei numeri di versione
  * **Supporto multi-estensione** - Pacchettizzare più estensioni contemporaneamente
  * **Pubblicazione Marketplace** - Pubblicazione diretta

===== Comandi =====

^ Comando ^ Descrizione ^
| ''WVDS: Create VSIX Package'' | Crea un pacchetto VSIX |
| ''WVDS: Publish Package'' | Pubblica su VS Marketplace |

===== Creare pacchetti VSIX =====

==== Prerequisiti ====

  * Node.js installato
  * Tool ''vsce'' disponibile: <code bash>
npm install -g @vscode/vsce
</code>

==== Flusso di lavoro ====

  - Assicuratevi che il progetto compili
  - ''Ctrl+Shift+P'' -> ''WVDS: Create VSIX Package''
  - Selezionate l'estensione (se ce ne sono più di una)
  - Il pacchetto viene creato in ''binaries/dist/''

==== Output ====

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

===== Gestione versioni =====

==== Semantic Versioning ====

La suite utilizza Semantic Versioning (SemVer):

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

^ Parte ^ Incrementare quando ^
| MAJOR | Breaking changes, modifiche API incompatibili |
| MINOR | Nuove funzionalità, retrocompatibile |
| PATCH | Bug fix, nessuna modifica alle funzionalità |

==== Incremento automatico ====

Durante la pacchettizzazione, la versione può essere incrementata automaticamente:
  - Selezionate "Increment Version" nel dialogo
  - Scegliete la parte da incrementare (MAJOR, MINOR, PATCH)
  - Il package.json viene aggiornato

==== Versioni pre-release ====

Per release beta:
<code>
1.0.0-beta.1
1.0.0-rc.1
</code>

===== Pacchettizzazione multi-estensione =====

La suite è composta da più estensioni che possono essere pacchettizzate insieme.

==== Extension Pack ====

Un Extension Pack raggruppa più estensioni:

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

==== Pacchettizzazione batch ====

Pacchettizzare tutte le estensioni in una volta:
  - ''WVDS: Create VSIX Package''
  - Selezionate "All Extensions"
  - Tutti i pacchetti vengono creati

===== Pubblicazione su Marketplace =====

==== Prerequisiti ====

  - **Organizzazione Azure DevOps** - Per account publisher
  - **Personal Access Token (PAT)** - Con permessi Marketplace
  - **Publisher ID** - Registrato su marketplace.visualstudio.com

==== Creare un publisher ====

  - Visitate [[https://marketplace.visualstudio.com/manage|marketplace.visualstudio.com/manage]]
  - Create un publisher
  - Annotate il Publisher ID

==== Creare un PAT ====

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

==== Pubblicare ====

  - ''WVDS: Publish Package''
  - Inserite il PAT (viene memorizzato in modo sicuro)
  - L'estensione viene caricata

<note warning>Non pubblicate estensioni con dati sensibili!</note>

===== Controlli pre-pubblicazione =====

Prima della pubblicazione vengono controllati automaticamente:

^ Controllo ^ Descrizione ^
| Version | Deve essere superiore alla versione pubblicata |
| README | Deve essere presente e non vuoto |
| CHANGELOG | Deve contenere le modifiche per la versione corrente |
| License | Deve essere specificata |
| Icon | Consigliato (PNG 128x128) |
| Repository | Consigliato (link al codice sorgente) |

===== Requisiti package.json =====

Per la pubblicazione su Marketplace:

<code json>
{
  "name": "wvds-vscode-core",
  "displayName": "WvdS VSCode Core",
  "description": "Infrastruttura centrale per 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>

===== Installazione locale =====

Per testare prima della pubblicazione:

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

Oppure in VS Code:
  - Extensions -> "..." -> "Install from VSIX..."
  - Selezionate il file VSIX

===== Risoluzione dei problemi =====

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

**Causa:** vsce non installato.

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

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

**Causa:** Publisher ID in package.json non corrisponde al publisher registrato.

**Soluzione:**
  - Controllate il Publisher ID in package.json
  - Assicuratevi che il publisher sia registrato

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

**Causa:** Questa versione è già stata pubblicata.

**Soluzione:**
  - Incrementate il numero di versione
  - Utilizzate la funzione Increment

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

**Causa:** Personal Access Token scaduto.

**Soluzione:**
  - Create un nuovo PAT
  - Inseritelo alla prossima pubblicazione

===== Dettagli tecnici =====

^ Proprietà ^ Valore ^
| Extension ID | wvds.wvds-vscode-packaging |
| Attivazione | onCommand:wvds.packaging.create |
| Dipendenze | wvds-vscode-core, wvds-vscode-build |
| Min. VS Code | 1.85.0 |

===== Vedere anche =====

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