Vai al contenuto

Versione di prodotto

Architecture Coffee usa il campo version del package.json root come unica sorgente autorevole della release applicativa. Il valore corrente deve essere letto dalla sorgente e dalle proiezioni validate, non duplicato in questa pagina.

Release notes e changelog 2.0.0

La release 2.0.0 rende esplicito il nuovo confine backend-only di Architecture Coffee: il repository distribuisce soltanto API Worker, server MCP, D1, workflow editoriali, integrazioni e rendering email. Frontend web, Admin UI, toolchain e runtime frontend non fanno più parte del prodotto distribuito.

La superficie MCP editoriale include ora operazioni API-backed, nominative e bounded per Topic, Knowledge Asset, glossario, lifecycle delle Issue, lista contatti Mailjet e campagne email. Preparazione del Campaign Draft, caricamento contenuto, scheduling, delivery e riconciliazione restano operazioni separate; il deploy non pubblica contenuti, non gestisce contatti e non invia email.

Breaking change

  • il frontend web e i relativi contratti/runtime sono rimossi;
  • API e MCP sono gli unici runtime applicativi distribuiti;
  • client o procedure che dipendevano dall'Admin UI o da route HTML non-email devono migrare ai contratti API/MCP supportati.

Gli hostname canonici API/MCP e i contratti JSON restano invariati. Il major bump non introduce un prefisso /v2, non cambia il protocollo MCP e non pubblica pacchetti npm.

Migrazioni e compatibilità

La release include 0033_email_channel_operation_attempts.sql, migrazione repository-owned additiva per i tentativi bounded del canale email e il fuso orario delle campagne. Deve essere applicata serialmente per ambiente, prima dell'API e del server MCP 2.0.0, usando esclusivamente il workflow protetto della release. Il precedente ritiro dello schema frontend è già completato e non viene ripetuto.

API, MCP, OpenAPI, permission registry e binding Worker devono esporre la stessa versione. Qualunque drift, migrazione inattesa o incompatibilità blocca il passaggio all'ambiente successivo.

Rollback

Il rollback applicativo ripristina separatamente le versioni Worker API e MCP identificate nel preflight. Non modifica D1. Dopo l'applicazione di 0033, un problema di schema richiede una migrazione forward correttiva o una procedura di recovery esplicitamente autorizzata; non è ammessa compensazione automatica. Rollback e recovery devono essere seguiti da health, version, Access, tool scan e verifiche D1 in sola lettura.

Proiezioni controllate

Il comando repository-owned sincronizza e verifica:

  • i metadata del workspace MCP;
  • il lockfile e le relative entry dei workspace;
  • APP_VERSION development e production dell'API;
  • APP_VERSION development e production del Worker MCP;
  • info.version del contratto OpenAPI.

I tipi Worker che proiettano APP_VERSION restano artefatti di Wrangler: npm run types li genera con il relativo hash e npm run types:check ne verifica il drift.

L'API restituisce la versione autorevole tramite GET /health e GET /version. Il Worker MCP la restituisce nella health quando è ready e nel campo serverInfo.version dell'handshake initialize. Una configurazione MCP con versione divergente resta not_ready.

Bump futuro

Modificare soltanto la sorgente autorevole e rigenerare:

npm pkg set version=2.0.0
npm run version:sync
npm run types
npm run version:check
npm run types:check

Sostituire 2.0.0 con la nuova Semantic Version approvata. version:sync è idempotente e aggiorna soltanto le proiezioni dichiarate; version:check fallisce su Semantic Version non valida, proiezioni divergenti o struttura attesa mancante. Il controllo è parte della CI.

Dopo la sincronizzazione eseguire test, typecheck, generazione OpenAPI, build, dry-run e documentazione richiesti dalla Story. I comandi di versione non distribuiscono ambienti e non pubblicano pacchetti.

Il bump vive nel normale delivery repository quando è richiesto dal prodotto. Non è necessaria una release-only PR per autorizzare Worker deployment. version:sync aggiorna soltanto le proiezioni di versione repository-owned controllate dalla CI.

Un bump non autorizza Production e non crea automaticamente Git tag, GitHub Release o deployment.

Concetti distinti

La versione di prodotto non modifica automaticamente:

  • gli URL API, per esempio non introduce /v1;
  • openapi: 3.0.3, che identifica la specifica OpenAPI;
  • la versione del protocollo MCP o dell'MCP SDK;
  • lo schema D1 o le migrazioni;
  • il formato Issue Content JSON;
  • la versione dello schema dell'editorial plan;
  • le versioni delle dipendenze.

Merge, deploy, tag Git, GitHub Release e pubblicazione npm sono operazioni distinte. Il bump repository non le esegue.

Per la normale release Production API/MCP, l'intento esplicito di Fra e il delivery scope già revisionato autorizzano il parameter-free workflow_dispatch su main. Il workflow congela il candidate e richiede CI verde più una release Development verde sullo stesso commit.

Versione prodotto, Git tag, GitHub Release e Worker deployment restano lifecycle distinti. Un tag non autorizza né attiva Production.

Non servono una Issue di rollout duplicata, un Project transition, un secondo go o micro-autorizzazioni. Il recupero di un bug Production segue la stessa regola quando richiede soltanto il normale Worker release reversibile; una recovery con operazioni o rischio materialmente distinti richiede invece una Issue operativa separata e revisionata.