From 867ec82f3f895f614693219e6687d94b82172a39 Mon Sep 17 00:00:00 2001 From: Giuseppe Ferro Date: Tue, 10 Nov 2026 18:26:15 +0100 Subject: [PATCH] docs: AP-5359 verify OKF bundle of zcs-python-core Mark the 12 bundle cards as stable and verified (human:gferro) after the explicit confirmation of the developer. Update the wording of okf/index.md. Co-Authored-By: Claude Sonnet 5.5 --- okf/api/eccezioni.md | 3 ++- okf/api/logger.md | 3 ++- okf/api/sessione.md | 3 ++- okf/api/telemetria.md | 3 ++- okf/comportamenti.md | 3 ++- okf/consumatori.md | 3 ++- okf/flussi/ciclo-di-vita-contesto-richiesta.md | 3 ++- okf/index.md | 2 +- okf/libreria.md | 3 ++- okf/operativita/configurazione.md | 3 ++- okf/operativita/rilascio.md | 3 ++- okf/questioni-aperte.md | 3 ++- okf/versioni.md | 3 ++- 13 files changed, 25 insertions(+), 13 deletions(-) diff --git a/okf/api/eccezioni.md b/okf/api/eccezioni.md index 984501c..99ea4ed 100644 --- a/okf/api/eccezioni.md +++ b/okf/api/eccezioni.md @@ -4,8 +4,9 @@ title: "Eccezioni: ZcsException" description: "ZcsException: parametri, codice di errore casuale, serializzazione con get_as_dict e legame con il logger." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/exception/exception.py tags: [eccezioni, zcs-exception, error-code] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: exc, resource: ../../app/src/zcs/core/exception/exception.py, title: "ZcsException", last_modified: 2025-10-15T08:50:58Z } - { id: logger, resource: ../../app/src/zcs/core/logger/logger.py, title: "Uso del codice di errore nel logger", last_modified: 2026-04-03T07:58:22Z } diff --git a/okf/api/logger.md b/okf/api/logger.md index 69572e9..d735256 100644 --- a/okf/api/logger.md +++ b/okf/api/logger.md @@ -4,8 +4,9 @@ title: "Logger: ZcsLogging e filtro degli endpoint" description: "ZcsLogging, i due formatter (JSON per Cloud Logging e console) e EndpointFilter: parametri, formato dei log e campi del contesto aggiunti." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/logger/logger.py tags: [logger, cloud-logging, formatter, endpoint-filter] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: logger, resource: ../../app/src/zcs/core/logger/logger.py, title: "ZcsLogging e formatter", last_modified: 2026-04-03T07:58:22Z } - { id: filter, resource: ../../app/src/zcs/core/logger/endpoint_filter.py, title: "EndpointFilter", last_modified: 2025-06-27T08:46:03Z } diff --git a/okf/api/sessione.md b/okf/api/sessione.md index fb15997..8a05f23 100644 --- a/okf/api/sessione.md +++ b/okf/api/sessione.md @@ -4,8 +4,9 @@ title: "Sessione: RequestState e contesto della richiesta" description: "Classi e funzioni di zcs.core.session: RequestState, request_context, AuthInfo, QaInfo, FolliaModule, con campi, valori predefiniti e chi li imposta." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/session/request_state.py tags: [sessione, request-state, contextvar, auth-info] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: state, resource: ../../app/src/zcs/core/session/request_state.py, title: "RequestState", last_modified: 2026-05-13T15:29:36Z } - { id: ctx, resource: ../../app/src/zcs/core/session/request_context.py, title: "request_context", last_modified: 2025-10-15T08:50:58Z } diff --git a/okf/api/telemetria.md b/okf/api/telemetria.md index d1dcdca..fa6f7af 100644 --- a/okf/api/telemetria.md +++ b/okf/api/telemetria.md @@ -4,8 +4,9 @@ title: "Telemetria: ZcsTelemetry, setup_logging, set_trace_attributes" description: "Cosa offre zcs.core.telemetry: inizializzazione con OTLP o Alloy, contatori, strumentazione FastAPI, log verso Loki e attributi delle tracce." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/telemetry/zcs_telemetry.py tags: [telemetria, opentelemetry, prometheus, loki, alloy, grafana] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: tel, resource: ../../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "ZcsTelemetry", last_modified: 2026-07-23T09:06:44Z } - { id: log, resource: ../../app/src/zcs/core/telemetry/logging.py, title: "setup_logging e LokiContextFilter", last_modified: 2026-05-12T08:23:34Z } diff --git a/okf/comportamenti.md b/okf/comportamenti.md index b0b1713..fe28742 100644 --- a/okf/comportamenti.md +++ b/okf/comportamenti.md @@ -4,8 +4,9 @@ title: "Comportamenti da conoscere" description: "Cosa succede davvero quando un servizio usa la libreria: contesto assente, effetti globali del logger, errori dei contatori, campi inviati a Loki, importazioni con effetti." resource: https://github.com/zcsadmin/zcs-python-core/tree/main/app/src/zcs/core tags: [comportamenti, logger, contatori, loki, contesto] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: logger, resource: ../app/src/zcs/core/logger/logger.py, title: "Logger e formatter", last_modified: 2026-04-03T07:58:22Z } - { id: tel, resource: ../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "ZcsTelemetry", last_modified: 2026-07-23T09:06:44Z } diff --git a/okf/consumatori.md b/okf/consumatori.md index 64e8a11..a85c760 100644 --- a/okf/consumatori.md +++ b/okf/consumatori.md @@ -4,8 +4,9 @@ title: "Chi usa zcs-python-core" description: "Servizi e librerie che dipendono da zcs-python-core: versione richiesta su main, versione richiesta al tag in produzione, versione del servizio in app_versions e moduli importati." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/okf/consumatori.md tags: [consumatori, versioni, produzione, app-versions] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: lettura, resource: "git grep su origin/main di tutte le repo di Follia_SW e git show dai tag, 2026-11-10", title: "Lettura delle dipendenze dei consumatori" } - { id: tfvars, resource: "app/follia.ai/terraform/terraform.tfvars di ml-follia-tesseract (origin/main 30bdc2f, file modificato il 2026-11-05)", title: "Mappa app_versions, letta il 2026-11-10" } diff --git a/okf/flussi/ciclo-di-vita-contesto-richiesta.md b/okf/flussi/ciclo-di-vita-contesto-richiesta.md index ae3d5bb..f059694 100644 --- a/okf/flussi/ciclo-di-vita-contesto-richiesta.md +++ b/okf/flussi/ciclo-di-vita-contesto-richiesta.md @@ -4,8 +4,9 @@ title: "Ciclo di vita del contesto della richiesta" description: "Come il contesto (RequestState in request_context) nasce, viene compilato e letto dal logger e dalla telemetria: cosa fa la libreria e cosa fa ogni servizio." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/session/request_context.py tags: [contesto, request-state, middleware, tracciamento] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: ctx, resource: ../../app/src/zcs/core/session/request_context.py, title: "request_context", last_modified: 2025-10-15T08:50:58Z } - { id: state, resource: ../../app/src/zcs/core/session/request_state.py, title: "RequestState", last_modified: 2026-05-13T15:29:36Z } diff --git a/okf/index.md b/okf/index.md index a1d59fe..de30195 100644 --- a/okf/index.md +++ b/okf/index.md @@ -4,7 +4,7 @@ okf_version: "0.2" # Bundle OKF di zcs-python-core -Schede che descrivono la libreria Python `zcs-python-core` vista da chi la usa: cosa offre, come si comporta, chi la usa e come si rilascia. Ogni scheda ha `status: draft` finché una persona non la verifica (`status: stable` con `verified`). +Schede che descrivono la libreria Python `zcs-python-core` vista da chi la usa: cosa offre, come si comporta, chi la usa e come si rilascia. Le schede nascono `draft` e passano a `stable` con `verified` quando una persona le controlla; quelle di questo bundle sono state verificate il 10/11/2026. * [Panoramica della libreria](libreria.md) - cosa offre, installazione, dipendenze e dove guardare * [Comportamenti da conoscere](comportamenti.md) - contesto assente, effetti globali del logger, errori dei contatori, campi inviati a Loki diff --git a/okf/libreria.md b/okf/libreria.md index 3a123ec..8030736 100644 --- a/okf/libreria.md +++ b/okf/libreria.md @@ -5,8 +5,9 @@ description: "Libreria Python di base per i servizi Follia: contesto della richi resource: https://github.com/zcsadmin/zcs-python-core/blob/main/README.md tags: [libreria, python, core, contesto-richiesta, logger, telemetria] esposizione: libreria -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: readme, resource: ../README.md, title: "README della repo", last_modified: 2025-06-27T08:46:03Z } - { id: pyproject, resource: ../app/pyproject.toml, title: "Metadati del pacchetto", last_modified: 2025-10-15T08:50:58Z } diff --git a/okf/operativita/configurazione.md b/okf/operativita/configurazione.md index 2577327..b12ab2e 100644 --- a/okf/operativita/configurazione.md +++ b/okf/operativita/configurazione.md @@ -4,8 +4,9 @@ title: "Configurazione della telemetria" description: "Variabili d'ambiente di TelemetrySettings (solo nomi e predefiniti), file letto, campi non usati; il resto della libreria non legge variabili." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/app/src/zcs/core/settings/telemetry_settings.py tags: [configurazione, telemetria, variabili-ambiente] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: sett, resource: ../../app/src/zcs/core/settings/telemetry_settings.py, title: "TelemetrySettings", last_modified: 2026-05-12T08:23:34Z } - { id: tel, resource: ../../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "Uso delle impostazioni", last_modified: 2026-07-23T09:06:44Z } diff --git a/okf/operativita/rilascio.md b/okf/operativita/rilascio.md index 52bc6ab..63e58dd 100644 --- a/okf/operativita/rilascio.md +++ b/okf/operativita/rilascio.md @@ -4,8 +4,9 @@ title: "Rilascio e prove in locale" description: "Come si pubblica zcs-python-core: workflow della PR e del tag, cosa non parte con un push su main, stato pre-release delle release lette, bug dell'identificativo, prove in locale." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/.github/workflows/publish-tag.yaml tags: [rilascio, workflow, artifact-registry, tag, test] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: publish, resource: ../../.github/workflows/publish-tag.yaml, title: "Pubblicazione sul tag", last_modified: 2026-07-23T09:21:16Z } - { id: pr, resource: ../../.github/workflows/pr_build-and-test.yaml, title: "Build e test sulle PR", last_modified: 2026-07-23T09:06:44Z } diff --git a/okf/questioni-aperte.md b/okf/questioni-aperte.md index 2a040f8..a71532c 100644 --- a/okf/questioni-aperte.md +++ b/okf/questioni-aperte.md @@ -4,8 +4,9 @@ title: "Questioni aperte e limiti noti" description: "Problemi di sicurezza, dipendenze, contatori, rilascio e documenti superati di zcs-python-core, con priorità; incongruenze trovate durante la stesura." resource: https://github.com/zcsadmin/zcs-python-core/blob/main/okf/questioni-aperte.md tags: [questioni-aperte, sicurezza, dipendenze, rilascio] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: tlog, resource: ../app/src/zcs/core/telemetry/logging.py, title: "setup_logging e LokiContextFilter", last_modified: 2026-05-12T08:23:34Z } - { id: tel, resource: ../app/src/zcs/core/telemetry/zcs_telemetry.py, title: "ZcsTelemetry", last_modified: 2026-07-23T09:06:44Z } diff --git a/okf/versioni.md b/okf/versioni.md index 01bffe1..fa68306 100644 --- a/okf/versioni.md +++ b/okf/versioni.md @@ -4,8 +4,9 @@ title: "Storia delle versioni" description: "Tag di zcs-python-core dal 2025: data, cosa cambia nel codice, modifiche non retrocompatibili e vincoli noti dal codice." resource: https://github.com/zcsadmin/zcs-python-core/tags tags: [versioni, tag, release] -status: draft +status: stable generated: { by: claude-code/claude-sonnet-5-5, at: 2026-11-10T17:05:00Z } +verified: { by: human:gferro, at: 2026-11-10T17:26:03Z } sources: - { id: git, resource: "git log e git diff tra i tag della repo, letti il 2026-11-10", title: "Storia dei tag" } - { id: rel, resource: "gh release list e gh api repos/zcsadmin/zcs-python-core/releases, 2026-11-10", title: "Release GitHub e stato pre-release" }