ICS → Importateur Discourse via API REST

Greffon Suppléments
,
12

Notes de comportement issues des tests de ics_to_discourse.py

J’ai effectué une série de tests sur ce script (avec et sans --time-only-dedupe) et j’ai pensé qu’il serait utile de documenter en détail le flux de mise à jour/adoption.

1. Comment l’unicité est déterminée

  • Mode par défaut : l’adoption nécessite que début + fin + lieu correspondent exactement.
  • Avec --time-only-dedupe : l’adoption ne nécessite que début + fin ; le lieu est considéré comme “suffisamment proche”.

Si aucun sujet existant ne correspond à ces règles, un nouveau sujet est créé.

2. Le rôle du marqueur UID

  • Chaque sujet d’événement reçoit un marqueur HTML caché dans le premier message :
  <!-- ICSUID:xxxxxxxxxxxxxxxx -->
  • Lors des exécutions suivantes, le script recherche d’abord ce marqueur.
  • S’il est trouvé, le sujet est considéré comme une correspondance UID et est mis à jour directement, quelle que soit la quantité de bruit ou l’ancienneté du texte DESCRIPTION.
  • Cela fait de l’UID la véritable clé d’identité. Les champs de description visibles n’affectent pas la correspondance.

3. Flux de mise à jour avec correspondance UID

  1. Le script récupère le premier message et supprime le marqueur :
 old_clean = strip_marker(old_raw)
 fresh_clean = strip_marker(fresh_raw)
  1. Si old_clean == fresh_clean : pas de mise à jour (évite le roulement).
  2. S’ils diffèrent : vérifie si le changement est “significatif” :
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"))
)
  • Si meaningful = True → mise à jour avec “bump” (le sujet remonte dans les Derniers).
  • Si meaningful = False → mise à jour silencieuse (bypass_bump=True → révision uniquement, pas de “bump”).
  1. Les tags sont fusionnés (garantit la présence des tags statiques/par défaut, ne supprime jamais les tags de modérateur/manuels).
  2. Le titre et la catégorie ne sont jamais modifiés lors d’une mise à jour.
  1. Flux de mise à jour sans correspondance UID
  2. Le script tente l’adoption :
    • Construit des triplets candidats de début/fin/lieu (ou début/fin uniquement avec --time-only-dedupe).
    • Recherche dans /search.json et /latest.json un événement existant avec des attributs correspondants.
    • Si trouvé → adopte ce sujet, ajoute le marqueur UID + les tags (le corps reste inchangé à ce stade).
    • Si non trouvé → crée un tout nouveau sujet avec le marqueur et les tags.
  3. Une fois adopté ou créé, toutes les synchronisations futures seront résolues directement par UID.

⸻

  1. Conséquences pratiques
    • Changements d’heure
    • Par défaut : l’adoption échoue (les heures diffèrent) → nouveau sujet créé.
    • Avec --time-only-dedupe : l’adoption échoue de la même manière ; nouveau sujet créé.
    • Changements de lieu
    • Par défaut : l’adoption échoue (le lieu diffère) → nouveau sujet créé.
    • Avec --time-only-dedupe : l’adoption réussit (les heures correspondent), mais la différence de lieu est signalée comme “significative” → mise à jour avec “bump”.
    • Changements de description
    • Si le texte DESCRIPTION change mais que le début/la fin/le lieu ne changent pas :
    • Le corps est mis à jour silencieusement (bypass_bump=True).
    • Une révision du sujet est créée, mais pas de “bump” dans les Derniers.
    • Si DESCRIPTION est inchangé (ou seulement du bruit comme Last Updated: qui se normalise), aucune mise à jour n’est effectuée.
    • Marqueur UID
    • Garantit une correspondance fiable lors des futures synchronisations.
    • Signifie que les champs DESCRIPTION bruyants n’affectent pas la recherche du bon sujet.

⸻

  1. Pourquoi la DESCRIPTION reste parfois “la même”
    Le script compare l’intégralité du corps (moins le marqueur UID).
    Si seule une ligne volatile comme Last Updated: est différente, mais qu’elle se normalise (par exemple, espaces blancs, fins de ligne, Unicode), old_clean et fresh_clean apparaissent identiques → aucune mise à jour n’est effectuée.
    C’est intentionnel, pour éviter le roulement dû au bruit du flux.

⸻

Résumé
• L’heure définit l’unicité (crée toujours un nouveau sujet lorsque les heures changent).
• Changements de lieu → “bump” visible (pour que les utilisateurs remarquent les mises à jour de lieu).
• Changements de description → mise à jour silencieuse (révision mais pas de “bump”).
• Le marqueur UID = clé d’identité fiable, garantit que le bon sujet est toujours trouvé, même si la DESCRIPTION est obsolète ou bruyante.

Cela établit un bon équilibre : les changements importants apparaissent dans les Derniers, le roulement sans importance reste invisible.