Quelle commande, quand
Pour l’itération locale au quotidien, vous voudrez presque toujours
yarn twenty dev. Le déploiement et la publication servent à livrer des versions, pas pour la boucle locale.yarn twenty dev --once et yarn twenty dev --once --dry-run fonctionnent toujours comme alias obsolètes de yarn twenty apply et yarn twenty plan.La synchronisation locale n’a pas besoin d’un incrément de version
La règle deversion strictement croissante (VERSION_ALREADY_EXISTS lors du déploiement, APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION lors de l’installation) s’applique à app:publish / app:install — le chemin de mise en production. yarn twenty dev synchronise votre manifeste sur place et ne nécessite jamais de changement de version, vous n’avez donc pas besoin de toucher à package.json pour itérer. Si vous vous surprenez à incrémenter la version pour tester un changement local, c’est que vous utilisez le chemin de mise en production alors que vous voulez la boucle de développement.
Lire la sortie de synchronisation
Chaque synchronisation affiche les changements de métadonnées qu’elle a appliqués (ou qu’elle appliquerait, avecplan), à la manière de Terraform — un bloc par entité avec ses attributs, puis une ligne récapitulative :
to destroy) sont listés avec ce qu’ils suppriment (par ex. objectMetadata "auditNote" — drops the table and all its rows) et nécessitent une confirmation interactive, ou --force dans les scripts.
Lorsqu’une synchronisation échoue sur une seule entité, l’erreur nomme l’entité en cause et son universalIdentifier, par exemple :
Prévisualiser les changements (plan)
yarn twenty plan construit votre manifeste, demande au serveur le plan de migration et l’affiche — sans rien appliquer. C’est le moyen sûr de répondre « que changerait cette synchronisation ? » avant de s’y engager.
- N’écrit rien — aucune migration de métadonnées, aucune mise à jour de l’enregistrement d’application, aucun changement de rôle/onglet par défaut, et aucune génération de client d’API.
- Renvoie le même diff qu’une synchronisation réelle appliquerait, afin que vous puissiez examiner à l’avance les entités créées/mises à jour/supprimées.
- Est utile avant un changement risqué, lors de la révision d’un changement généré par une IA, ou dans un script qui doit échouer si un changement inattendu est sur le point d’être appliqué.
Un plan ne prévisualise que les changements de métadonnées, et il nécessite que l’application ait été synchronisée au moins une fois (pour que l’espace de travail la connaisse). Si vous l’exécutez sur une application qui n’a jamais été synchronisée, le serveur indique que l’application n’est pas installée — exécutez d’abord une fois
yarn twenty dev.Échelle de récupération
Lorsque les métadonnées locales semblent incorrectes, augmentez le niveau de manière progressive dans cet ordre et arrêtez-vous dès que vous êtes débloqué. Chaque étape est plus perturbatrice que la précédente.- Resynchroniser. Exécutez à nouveau
yarn twenty apply. Les synchronisations sont idempotentes — réexécuter un manifeste propre est sûr et résout souvent un incident passager. - Prévisualiser le plan. Exécutez
yarn twenty planpour voir exactement ce que la prochaine synchronisation compte changer, sans l’appliquer. - Lire l’erreur nommée. Si une synchronisation échoue, relevez le type de métadonnées et l’
universalIdentifierdans le message (voir ci-dessus) et localisez cette entité dans votre manifeste. Un conflit pointe généralement vers un identifiant dupliqué ou réutilisé. - Désinstaller et réinstaller.
yarn twenty app:uninstall, puis synchronisez à nouveau (yarn twenty dev). Cette opération reconstruit les métadonnées de l’application à partir d’une base saine tout en gardant le reste de votre espace de travail intact. - Réinitialisation complète (en dernier recours).
yarn twenty docker:reset, puis réinjectez des données et resynchronisez.
Vous avez rencontré une erreur de métadonnées ? Veuillez ouvrir un ticket et inclure le message d’échec de migration (avec son type de métadonnées et son
universalIdentifier), la sortie Metadata changes de la synchronisation, ainsi que les commandes que vous avez exécutées.Éviter les synchronisations concurrentes sur un même espace de travail
La synchronisation applique des migrations de métadonnées. Exécuter plusieurs opérations de synchronisation, de déploiement ou d’installation contre le même espace de travail au même moment — par exemple, plusieurs terminaux ou agents IA qui itèrent en parallèle — peut entrelacer ces migrations et laisser les métadonnées dans un état partiellement appliqué. Le serveur sérialise les synchronisations par espace de travail pour éviter cela, mais vous devriez tout de même faire transiter les opérations sensibles sur les métadonnées par un processus unique plutôt que de les lancer en concurrence. Si vous orchestrez le développement avec plusieurs agents, faites passer leurs appels de synchronisation/déploiement/installation par une file unique afin qu’un seul s’exécute à la fois.Distinguer les types d’échecs
Lorsque quelque chose se passe mal, le diff de métadonnées et les erreurs nommées vous permettent de localiser l’échec :- Erreur de construction du manifeste — le CLI échoue avant la synchronisation (
MANIFEST_BUILD_FAILED,TYPECHECK_FAILED) ; corrigez le code source de votre application. - Erreur de synchronisation / migration — la construction réussit mais l’application du diff échoue, en nommant l’entité et son
universalIdentifier; corrigez les métadonnées en conflit. - Erreur d’exécution du code de l’application — la synchronisation réussit, mais vos fonctions logiques ou composants se comportent mal à l’exécution ; consultez les journaux de fonctions.
- État local de l’instance — aucun des cas ci-dessus et l’espace de travail semble toujours incorrect ; descendez l’échelle de récupération.