ICS → Discourse-importeur via REST API

Plugin Extra's
,
12

Gedragsnotities van het testen van ics_to_discourse.py

Ik heb een reeks tests uitgevoerd op dit script (met en zonder --time-only-dedupe) en dacht dat het nuttig zou zijn om de update/adoptiestroom in detail te documenteren.

1. Hoe uniciteit wordt bepaald

  • Standaardmodus: adoptie vereist dat start + eind + locatie exact overeenkomen.
  • Met --time-only-dedupe: adoptie vereist alleen start + eind; locatie wordt behandeld als “dichtbij genoeg”.

Als geen bestaand onderwerp aan deze regels voldoet, wordt een nieuw onderwerp aangemaakt.

2. De rol van de UID-marker

  • Elk evenementonderwerp krijgt een verborgen HTML-marker in het eerste bericht:
  <!-- ICSUID:xxxxxxxxxxxxxxxx -->
  • Bij volgende uitvoeringen zoekt het script eerst naar die marker.
  • Indien gevonden, wordt het onderwerp beschouwd als een UID-match en direct bijgewerkt, ongeacht hoe ruisend of verouderd de BESCHRIJVING-tekst is.
  • Dit maakt de UID de ware identiteitssleutel. Zichtbare beschrijvingsvelden hebben geen invloed op de matching.

3. Update-stroom met UID-match

  1. Script haalt het eerste bericht op en verwijdert de marker:
 old_clean = strip_marker(old_raw)
 fresh_clean = strip_marker(fresh_raw)
  1. Als old_clean == fresh_clean: geen update (voorkomt churn).
  2. Als ze verschillen: controleer of de wijziging “betekenisvol” is:
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"))
)
  • Als meaningful = True → update met bump (onderwerp stijgt in Laatste).
  • Als meaningful = False → update stilzwijgend (bypass_bump=True → alleen revisie, geen bump).
  1. Tags worden samengevoegd (zorgt ervoor dat statische/standaardtags aanwezig zijn, verwijdert nooit moderator/handmatige tags).
  2. Titel en categorie worden nooit gewijzigd bij een update.
  1. Update-stroom zonder UID-match
  2. Script probeert adoptie:
    • Bouwt kandidaat-triples van start/eind/locatie (of alleen start/eind met --time-only-dedupe).
    • Zoekt in /search.json en /latest.json naar een bestaand evenement met overeenkomende attributen.
    • Indien gevonden → adopteer dat onderwerp, pas UID-marker + tags aan (body blijft in dit stadium ongewijzigd).
    • Indien niet gevonden → maak een gloednieuw onderwerp aan met de marker en tags.
  3. Zodra geadopteerd of aangemaakt, zullen alle toekomstige synchronisaties direct via UID worden opgelost.

⸻

  1. Praktische gevolgen
    • Tijdswijzigingen
    • Standaard: adoptie mislukt (tijden verschillen) → nieuw onderwerp aangemaakt.
    • Met --time-only-dedupe: adoptie mislukt op dezelfde manier; nieuw onderwerp aangemaakt.
    • Locatiewijzigingen
    • Standaard: adoptie mislukt (locatie verschilt) → nieuw onderwerp aangemaakt.
    • Met --time-only-dedupe: adoptie slaagt (tijden komen overeen), maar locatiewijziging wordt gemarkeerd als “betekenisvol” → update met bump.
    • Beschrijvingswijzigingen
    • Als de BESCHRIJVING-tekst verandert, maar start/eind/locatie niet:
    • Body wordt stilzwijgend bijgewerkt (bypass_bump=True).
    • Onderwerp revisie aangemaakt, maar geen bump in Laatste.
    • Als BESCHRIJVING ongewijzigd is (of alleen ruis zoals Laatst bijgewerkt: dat normaliseert weg), vindt er helemaal geen update plaats.
    • UID-marker
    • Zorgt voor betrouwbare matching bij toekomstige synchronisaties.
    • Betekent dat ruisende BESCHRIJVING-velden er niet toe doen of het juiste onderwerp wordt gevonden.

⸻

  1. Waarom de BESCHRIJVING soms “hetzelfde blijft”
    Het script vergelijkt de volledige body (minus de UID-marker).
    Als alleen een vluchtige regel zoals Laatst bijgewerkt: anders is, maar deze normaliseert weg (bv. witruimte, regeleinden, Unicode), lijken old_clean en fresh_clean identiek → er wordt geen update uitgevoerd.
    Dit is opzettelijk, om churn door feed-ruis te voorkomen.

⸻

Samenvatting
• Tijd definieert uniciteit (creëert altijd een nieuw onderwerp wanneer tijden veranderen).
• Locatiewijzigingen → zichtbare bump (zodat gebruikers venue-updates opmerken).
• Beschrijvingswijzigingen → stille update (revisie maar geen bump).
• UID-marker = betrouwbare identiteitssleutel, zorgt ervoor dat het juiste onderwerp altijd wordt gevonden, zelfs als de BESCHRIJVING verouderd of ruisend is.

Dit biedt een goede balans: belangrijke wijzigingen komen naar voren in Laatste, onbelangrijke churn blijft onzichtbaar.