docs: add contributor site decommissioning guide

docs/contribute-decommission.es.md

@@ -0,0 +1,131 @@
+# Guía de desmantelamiento de sitio para contribuidores
+
+Esta guía describe cómo desmantelar un dispositivo DoubleZero (DZD) o dar de baja un sitio: cómo retirar sus dispositivos y enlaces de la red sin interrumpir a los usuarios conectados, y luego eliminarlos onchain.
+
+El proceso se ejecuta en tres fases: limitar el dispositivo 31 días antes del día de desmantelamiento, notificar a los usuarios conectados durante un período de aviso para que puedan migrar, y luego drenar y eliminar los enlaces, interfaces y el dispositivo el día del desmantelamiento.
+
+> ⚠️ **Coordine con DoubleZero primero:**
+> Siempre alinéese con el equipo de DoubleZero antes de desmantelar un dispositivo o sitio, y programe su fecha y hora de desmantelamiento con nosotros. Ejecutamos algunos pasos de nuestro lado alrededor de ese horario, por lo que necesitamos estar programados. Acuerde las fechas y el plan antes de limitar un dispositivo o drenar un enlace.
+
+> ⚠️ **Switches y enlaces DZX:**
+> Si el dispositivo que está desmantelando es un switch DZX, o tiene algún enlace DZX, identifique a los contribuidores afectados lo antes posible y notifíqueles, ya que es posible que necesiten mover o reconstruir sus enlaces antes de su fecha. También cree un evento de mantenimiento en el [portal OPS](contribute-ops-management.md) para la fecha de desmantelamiento.
+
+---
+
+## Resumen
+
+| Cuándo | Acción | Quién |
+|--------|--------|-------|
+| 31 días antes | Limitar el dispositivo para que nuevos usuarios no puedan conectarse (`--max-users 0`) | Contribuidor |
+| 14 días antes | Los usuarios conectados son notificados para migrar a otro dispositivo | Equipo de DoubleZero |
+| Período de aviso | Los usuarios se reconectan por su cuenta a otros DZDs | Usuarios |
+| Día de desmantelamiento | Drenar y eliminar los enlaces, interfaces y el dispositivo | Contribuidor |
+
+Principios:
+
+- **Detener nuevos usuarios temprano, migrar usuarios existentes gradualmente.** Limitar el dispositivo temprano significa que solo pierde usuarios a partir de ese momento. Los usuarios existentes siguen funcionando y migran según su propio calendario.
+- **Mantener todo activo durante el período de aviso.** No drene los enlaces ni el dispositivo hasta el día de desmantelamiento, para que los usuarios en proceso de migración mantengan el servicio normal.
+- **El orden de desmontaje es impuesto por el contrato.** No puede eliminar un enlace o dispositivo mientras esté activo, por lo que los pasos a continuación drenan primero y eliminan al final.
+
+> ⚠️ **Aviso con poco tiempo:**
+> Si tiene menos de 31 días antes de la salida, comience inmediatamente. Limite el dispositivo ahora y acorte los períodos para ajustarse al tiempo disponible. El orden de los pasos no cambia.
+
+---
+
+## Fase 1 — Limitar el dispositivo (31 días antes)
+
+Limite el dispositivo para que nuevos usuarios no puedan conectarse:
+
+```bash
+doublezero device update --pubkey <DEVICE_PUBKEY> --max-users 0
+```
+
+Los usuarios existentes no se ven afectados y siguen funcionando. Repita para cada dispositivo que se vaya a desmantelar en el sitio. Los enlaces y el dispositivo permanecen completamente activos, por lo que los usuarios conectados mantienen el servicio normal.
+
+---
+
+## Fase 2 — Período de aviso (14 días antes)
+
+El equipo de DoubleZero notifica a los usuarios conectados, pidiéndoles que se reconecten a un DZD diferente antes de la fecha de desmantelamiento. Coordine con el equipo sobre quién contacta a qué usuarios.
+
+No se drena nada durante este período, por lo que los usuarios mantienen el servicio normal. Los usuarios se reconectan a su propio ritmo. Monitoree el conteo de usuarios con:
+
+```bash
+doublezero device list
+```
+
+---
+
+## Fase 3 — Día de desmantelamiento
+
+Antes de comenzar, determine exactamente qué necesita ser eliminado: el dispositivo, los enlaces conectados a él y las interfaces a limpiar. Puede encontrar todo esto con:
+
+```bash
+doublezero device list | grep <CONTRIBUTOR_CODE>    # encontrar su dispositivo: su código y pubkey
+doublezero link list | grep <DEVICE_CODE>           # encontrar los enlaces conectados al dispositivo
+doublezero device interface list <DEVICE_CODE>      # listar las interfaces del dispositivo a eliminar
+```
+
+Ejecute estos pasos en orden. Cada paso desbloquea el siguiente.
+
+> ⚠️ **Antes de la eliminación final del dispositivo:**
+> Notifique a la Fundación DoubleZero antes de ejecutar el último paso. La Fundación elimina a cualquier usuario que no haya migrado a tiempo, lo cual de otro modo bloquearía la eliminación, y completa cualquier paso requerido del lado de la fundación.
+
+### 1. Drenar los enlaces
+
+Primero drenado suave, luego drenado fuerte. Consulte [Drenado de enlaces](contribute-operations.md#link-draining) para conocer qué hace cada estado.
+
+```bash
+doublezero link update --pubkey <LINK_PUBKEY> --status soft-drained
+# una vez que el tráfico se haya movido:
+doublezero link update --pubkey <LINK_PUBKEY> --status hard-drained
+```
+
+Repita para cada enlace en los dispositivos que se van a retirar.
+
+### 2. Eliminar los enlaces
+
+```bash
+doublezero link delete --pubkey <LINK_PUBKEY>
+```
+
+Esto libera las interfaces que los enlaces estaban usando.
+
+### 3. Eliminar las interfaces
+
+```bash
+doublezero device interface delete <DEVICE_CODE> <INTERFACE_NAME>
+```
+
+Repita para cada interfaz en el dispositivo.
+
+### 4. Drenar el dispositivo
+
+```bash
+doublezero device update --pubkey <DEVICE_PUBKEY> --status drained
+```
+
+El drenado elimina el dispositivo del enrutamiento y cierra cualquier sesión de usuario restante. También mueve el dispositivo fuera de su estado activo para que pueda ser eliminado.
+
+### 5. Eliminar el dispositivo
+
+```bash
+doublezero device delete --pubkey <DEVICE_PUBKEY>
+```
+
+El dispositivo solo puede ser eliminado una vez que ya no esté activo, no tenga enlaces que lo referencien y no le queden interfaces, lo cual los pasos anteriores se encargan de resolver.
+
+---
+
+## Cancelación o aplazamiento
+
+Limitar y drenar son reversibles hasta que comience a eliminar:
+
+```bash
+doublezero device update --pubkey <DEVICE_PUBKEY> --max-users <ORIGINAL_VALUE>   # restaurar capacidad
+doublezero link update --pubkey <LINK_PUBKEY> --status soft-drained             # desde hard-drained
+doublezero link update --pubkey <LINK_PUBKEY> --status activated                # volver a activo
+doublezero device update --pubkey <DEVICE_PUBKEY> --status activated            # revertir el drenado del dispositivo
+```
+
+Eliminar los enlaces, interfaces o el dispositivo es permanente: cierra las cuentas onchain. Solo comience a eliminar una vez que la salida esté confirmada.

docs/contribute-decommission.fr.md

@@ -0,0 +1,131 @@
+# Guide de désaffectation de site pour les contributeurs
+
+Ce guide décrit comment désaffecter un DoubleZero Device (DZD) ou quitter un site : comment retirer vos appareils et liens du réseau sans perturber les utilisateurs connectés, puis les supprimer on-chain.
+
+Le processus se déroule en trois étapes : plafonner l'appareil 31 jours avant le jour de la désaffectation, notifier les utilisateurs connectés pendant une fenêtre de préavis afin qu'ils puissent migrer, puis drainer et supprimer les liens, interfaces et l'appareil le jour de la désaffectation.
+
+> ⚠️ **Coordonnez-vous d'abord avec DoubleZero :**
+> Alignez-vous toujours avec l'équipe DoubleZero avant de désaffecter un appareil ou un site, et planifiez votre date et heure de désaffectation avec nous. Nous effectuons quelques étapes de notre côté autour de ce créneau, il est donc nécessaire de nous inclure dans la planification. Convenez des dates et du plan avant de plafonner un appareil ou de drainer un lien.
+
+> ⚠️ **Commutateurs et liens DZX :**
+> Si l'appareil que vous désaffectez est un commutateur DZX, ou possède des liens DZX, identifiez les contributeurs concernés le plus tôt possible et prévenez-les, car ils pourraient avoir besoin de déplacer ou reconstruire leurs liens avant votre date. Créez également un événement de maintenance dans le [portail OPS](contribute-ops-management.md) pour la date de désaffectation.
+
+---
+
+## Vue d'ensemble
+
+| Quand | Action | Qui |
+|-------|--------|-----|
+| 31 jours avant | Plafonner l'appareil pour qu'aucun nouvel utilisateur ne puisse s'y connecter (`--max-users 0`) | Contributeur |
+| 14 jours avant | Les utilisateurs connectés sont notifiés de migrer vers un autre appareil | Équipe DoubleZero |
+| Fenêtre de préavis | Les utilisateurs se reconnectent eux-mêmes à d'autres DZD | Utilisateurs |
+| Jour de la désaffectation | Drainer et supprimer les liens, interfaces et l'appareil | Contributeur |
+
+Principes :
+
+- **Bloquer les nouveaux utilisateurs tôt, migrer les utilisateurs existants progressivement.** Plafonner l'appareil tôt signifie qu'il ne perd des utilisateurs qu'à partir de ce moment. Les utilisateurs existants continuent de fonctionner et migrent à leur propre rythme.
+- **Tout maintenir en service pendant la fenêtre de préavis.** Ne drainez pas les liens ni l'appareil avant le jour de la désaffectation, afin que les utilisateurs en cours de migration conservent un service normal.
+- **L'ordre de démontage est imposé par le contrat.** Vous ne pouvez pas supprimer un lien ou un appareil tant qu'il est actif, les étapes ci-dessous procèdent donc au drainage d'abord et à la suppression en dernier.
+
+> ⚠️ **Préavis court :**
+> Si vous disposez de moins de 31 jours avant la sortie, commencez immédiatement. Plafonnez l'appareil maintenant et raccourcissez les fenêtres pour s'adapter au temps disponible. L'ordre des étapes ne change pas.
+
+---
+
+## Phase 1 — Plafonner l'appareil (31 jours avant)
+
+Plafonnez l'appareil pour qu'aucun nouvel utilisateur ne puisse s'y connecter :
+
+```bash
+doublezero device update --pubkey <DEVICE_PUBKEY> --max-users 0
+```
+
+Les utilisateurs existants ne sont pas affectés et continuent de fonctionner. Répétez l'opération pour chaque appareil en cours de désaffectation sur le site. Les liens et l'appareil restent pleinement actifs, de sorte que les utilisateurs connectés conservent un service normal.
+
+---
+
+## Phase 2 — Fenêtre de préavis (14 jours avant)
+
+L'équipe DoubleZero notifie les utilisateurs connectés, leur demandant de se reconnecter à un autre DZD avant la date de désaffectation. Coordonnez-vous avec l'équipe pour déterminer qui contacte quels utilisateurs.
+
+Rien n'est drainé pendant cette fenêtre, les utilisateurs conservent donc un service normal. Les utilisateurs se reconnectent eux-mêmes à leur propre rythme. Surveillez le nombre d'utilisateurs avec :
+
+```bash
+doublezero device list
+```
+
+---
+
+## Phase 3 — Jour de la désaffectation
+
+Avant de commencer, identifiez précisément ce qui doit être retiré : l'appareil, les liens qui y sont connectés et les interfaces à nettoyer. Vous pouvez trouver toutes ces informations avec :
+
+```bash
+doublezero device list | grep <CONTRIBUTOR_CODE>    # trouver votre appareil : son code et sa pubkey
+doublezero link list | grep <DEVICE_CODE>           # trouver les liens connectés à l'appareil
+doublezero device interface list <DEVICE_CODE>      # lister les interfaces de l'appareil à supprimer
+```
+
+Exécutez ces étapes dans l'ordre. Chaque étape déverrouille la suivante.
+
+> ⚠️ **Avant la suppression finale de l'appareil :**
+> Prévenez la DoubleZero Foundation avant d'exécuter la dernière étape. La Foundation supprime les utilisateurs qui n'ont pas migré à temps, ce qui bloquerait sinon la suppression, et complète toutes les étapes requises de son côté.
+
+### 1. Drainer les liens
+
+Effectuez d'abord un drainage progressif (soft-drain), puis un drainage complet (hard-drain). Consultez [Drainage des liens](contribute-operations.md#link-draining) pour comprendre ce que fait chaque état.
+
+```bash
+doublezero link update --pubkey <LINK_PUBKEY> --status soft-drained
+# une fois le trafic déplacé :
+doublezero link update --pubkey <LINK_PUBKEY> --status hard-drained
+```
+
+Répétez pour chaque lien sur les appareils en cours de retrait.
+
+### 2. Supprimer les liens
+
+```bash
+doublezero link delete --pubkey <LINK_PUBKEY>
+```
+
+Cela libère les interfaces que les liens utilisaient.
+
+### 3. Supprimer les interfaces
+
+```bash
+doublezero device interface delete <DEVICE_CODE> <INTERFACE_NAME>
+```
+
+Répétez pour chaque interface de l'appareil.
+
+### 4. Drainer l'appareil
+
+```bash
+doublezero device update --pubkey <DEVICE_PUBKEY> --status drained
+```
+
+Le drainage retire l'appareil du routage et ferme toutes les sessions utilisateur restantes. Il fait également sortir l'appareil de son état actif afin qu'il puisse être supprimé.
+
+### 5. Supprimer l'appareil
+
+```bash
+doublezero device delete --pubkey <DEVICE_PUBKEY>
+```
+
+L'appareil ne peut être supprimé que lorsqu'il n'est plus actif, qu'aucun lien ne le référence et qu'il ne reste aucune interface, ce que les étapes précédentes gèrent.
+
+---
+
+## Annulation ou report
+
+Le plafonnement et le drainage sont réversibles tant que vous n'avez pas commencé à supprimer :
+
+```bash
+doublezero device update --pubkey <DEVICE_PUBKEY> --max-users <ORIGINAL_VALUE>   # restaurer la capacité
+doublezero link update --pubkey <LINK_PUBKEY> --status soft-drained             # depuis hard-drained
+doublezero link update --pubkey <LINK_PUBKEY> --status activated                # retour à l'état actif
+doublezero device update --pubkey <DEVICE_PUBKEY> --status activated            # annuler le drainage de l'appareil
+```
+
+La suppression des liens, interfaces ou de l'appareil est permanente : elle ferme les comptes on-chain. Ne commencez à supprimer que lorsque la sortie est confirmée.