ICS → Importatore Discourse tramite API REST

Plugin Extra
,
12

Note sul comportamento dai test di ics_to_discourse.py

Ho eseguito una serie di test su questo script (con e senza --time-only-dedupe) e ho pensato che sarebbe stato utile documentare in dettaglio il flusso di aggiornamento/adozione.

1. Come viene determinata l’unicità

  • Modalità predefinita: l’adozione richiede che inizio + fine + posizione corrispondano esattamente.
  • Con --time-only-dedupe: l’adozione richiede solo inizio + fine; la posizione viene trattata come “sufficientemente vicina”.

Se nessun argomento esistente corrisponde a queste regole, viene creato un nuovo argomento.

2. Il ruolo del marcatore UID

  • Ogni argomento dell’evento riceve un marcatore HTML nascosto nel primo post:
  <!-- ICSUID:xxxxxxxxxxxxxxxx -->
  • Nelle esecuzioni successive, lo script cerca prima quel marcatore.
  • Se trovato, l’argomento viene considerato una corrispondenza UID e aggiornato direttamente, indipendentemente da quanto rumoroso o obsoleto possa essere il testo della DESCRIZIONE.
  • Ciò rende l’UID la vera chiave di identità. I campi di descrizione visibili non influiscono sulla corrispondenza.

3. Flusso di aggiornamento con corrispondenza UID

  1. Lo script recupera il primo post e rimuove il marcatore:

     old_clean = strip_marker(old_raw)
 fresh_clean = strip_marker(fresh_raw)

  2. Se old_clean == fresh_clean: nessun aggiornamento (evita il churn).

  3. Se differiscono: verifica se la modifica è “significativa”:

    meaningful = (
    _norm_time(old_attrs.get("start")) != _norm_time(new_attrs.get("start"))
    or _norm_time(old_attrs.get("end")) != _norm_time(new_attrs.get("end"))
    or _norm_loc(old_attrs.get("location")) != _norm_loc(new_attrs.get("location"))
)

  • Se meaningful = True → aggiorna con bump (l’argomento sale in “Latest”).

  • Se meaningful = False → aggiorna silenziosamente (bypass_bump=True → solo revisione, nessun bump).

    1. I tag vengono uniti (garantisce la presenza di tag statici/predefiniti, non rimuove mai quelli del moderatore/manuali).
    2. Titolo e categoria non vengono mai modificati durante l’aggiornamento.

  1. Flusso di aggiornamento senza corrispondenza UID

    1. Lo script tenta l’adozione:
      • Costruisce triple candidate di inizio/fine/posizione (o solo inizio/fine con --time-only-dedupe).
      • Cerca in /search.json e /latest.json un evento esistente con attributi corrispondenti.
      • Se trovato → adotta quell’argomento, ritocca il marcatore UID + tag (corpo lasciato invariato in questa fase).
      • Se non trovato → crea un argomento completamente nuovo con il marcatore e i tag.
    2. Una volta adottato o creato, tutte le sincronizzazioni future verranno risolte direttamente tramite UID.

⸻

  1. Conseguenze pratiche

    • Modifiche all’orario
    • Predefinito: l’adozione fallisce (gli orari differiscono) → viene creato un nuovo argomento.
    • Con --time-only-dedupe: l’adozione fallisce allo stesso modo; viene creato un nuovo argomento.
    • Modifiche alla posizione
    • Predefinito: l’adozione fallisce (la posizione differisce) → viene creato un nuovo argomento.
    • Con --time-only-dedupe: l’adozione ha successo (gli orari corrispondono), ma la differenza di posizione viene segnalata come “significativa” → aggiornamento con bump.
    • Modifiche alla descrizione
    • Se il testo della DESCRIZIONE cambia ma inizio/fine/posizione no:
    • Il corpo viene aggiornato silenziosamente (bypass_bump=True).
    • Viene creata una revisione dell’argomento, ma nessun bump in “Latest”.
    • Se la DESCRIZIONE è invariata (o solo rumore come “Last Updated:” che si normalizza), non viene apportato alcun aggiornamento.
    • Marcatore UID
    • Garantisce una corrispondenza affidabile nelle sincronizzazioni future.
    • Significa che i campi di DESCRIZIONE rumorosi non influiscono sulla ricerca dell’argomento corretto.

⸻

  1. Perché la DESCRIZIONE a volte “rimane la stessa”

Lo script confronta l’intero corpo (meno il marcatore UID).
Se solo una riga volatile come “Last Updated:” è diversa, ma si normalizza (ad es. spazi bianchi, terminazioni di riga, Unicode), old_clean e fresh_clean appaiono identici → non viene apportato alcun aggiornamento.
Questo è intenzionale, per evitare il churn dal rumore del feed.

⸻

Riepilogo

  • L’orario definisce l’unicità (crea sempre un nuovo argomento quando gli orari cambiano).
  • Le modifiche alla posizione → bump visibile (in modo che gli utenti notino gli aggiornamenti della sede).
  • Le modifiche alla descrizione → aggiornamento silenzioso (revisione ma nessun bump).
  • Marcatore UID = chiave di identità affidabile, garantisce che l’argomento corretto venga sempre trovato, anche se la DESCRIZIONE è obsoleta o rumorosa.

Ciò offre un buon equilibrio: le modifiche importanti emergono in “Latest”, il churn non importante rimane invisibile.