Guide de gestion multi-dépôt MonoSpecs

Aperçu

MonoSpecs est l’approche de gestion multi-référentiel de HagiCode. Il suit et gère les sous-référentiels via monospecs.yaml, et cela fonctionne pour tout projet nécessitant un seul endroit pour coordonner plusieurs référentiels indépendants.

Concepts de base

Fichier de configuration

monospecs.yaml est le cœur de toute la solution de gestion, définissant :

• Liste et emplacement des sous-référentiels
• URL Git pour chaque référentiel
• Nom d’affichage et icône
• Comportement d’intégration avec OpenSpec

Différences par rapport aux référentiels standards

Caractéristique	Dépôt régulier	Projet géré par MonoSpecs
Emplacement OpenSpec	Répertoire racine openspec/	Répertoire racine du référentiel principal openspec/
Modifier la portée	Limité au référentiel actuel	Peut impliquer plusieurs sous-dépôts
Pureté du sous-dépôt	Spécifications mélangées avec du code	Spécifications établies dans le référentiel principal, les sous-dépôts sont plus propres
** Archiver la validation automatique **	Nécessite des validations de spécifications manuelles	commit_when_archive: true valide automatiquement les spécifications dans le référentiel principal

Pourquoi utiliser les MonoSpecs ?

• Gestion unifiée : gérez tous les sous-dépôts dans un seul fichier de configuration
• Prise en charge de l’automatisation : fournit des métadonnées de référentiel pour les scripts et les outils
• Convivialité avec l’IA : la configuration structurée aide l’agent AI à comprendre les relations entre les référentiels
• Intégration OpenSpec : intégration transparente avec le flux de travail de gestion des changements
• Sous-dépôts plus propres : les spécifications sont conservées dans le dépôt principal, les sous-dépôts ne contiennent que le code réel

Scénarios applicables

Utilisez d’abord MonoSpecs dans des scénarios comme ceux-ci :

1. Développement collaboratif multi-dépôt Lorsqu’un projet est divisé en plusieurs référentiels indépendants :

• Application frontend, service backend et application de bureau développés séparément
• Nécessité de coordonner les versions et les dépendances entre les référentiels
• Projets de documentation et d’assistance séparés du code principal

2. Gestion de projet auxiliaire Utilisez MonoSpecs pour gérer :

• Projet documentaire
• Site officiel
• Créer des outils et des scripts
• Chaque référentiel maintient son propre contrôle de version

3. Développement de fonctionnalités inter-référentiels Une fonctionnalité qui nécessite des modifications sur plusieurs référentiels :

• Besoin de suivre les changements dans quels référentiels
• Valider automatiquement les spécifications dans le référentiel cible correct
• Coordonner les mises à jour de versions et les dépendances

Démarrage rapide

Initialisation

Suivez ces étapes pour terminer l’initialisation des monospecs :

1. Créer un référentiel git vide

Créer un vide git dossier dans votre référentiel principal (remarque : il s’agit de git, non repos/ - c’est la convention monospecs) :

mkdir git
cd git
git init
cd ..

2. Configurer le fichier monospecs

Créer le monospecs.yaml fichier de configuration dans le répertoire racine de votre référentiel principal :

version: "1.0"
commit_when_archive: true

repositories:
  - path: "repos/frontend"
    url: "https://github.com/your-org/frontend.git"
    displayName: "Frontend App"
    icon: "🌐"

  - path: "repos/backend"
    url: "https://github.com/your-org/backend.git"
    displayName: "Backend Service"
    icon: "⚙️"

Éléments de configuration :

Élément de configuration	Tapez	Obligatoire	Descriptif
version	chaîne	Oui	Version du fichier de configuration
commit_when_archive	booléen	Non	S’il faut valider automatiquement les spécifications lors de l’archivage (ne pas valider le code du sous-dépôt)
repositories	tableau	Oui	Liste de configuration du référentiel
repositories[].path	chaîne	Oui	Chemin du référentiel (par rapport à la racine du projet)
repositories[].url	chaîne	Oui	URL du dépôt Git
repositories[].displayName	chaîne	Non	Nom d’affichage du référentiel
repositories[].icon	chaîne	Non	Icône du référentiel (emoji)

Ajouter des sous-dépôts au référentiel principal

Ajoutez tous les sous-dépôts au repos/ répertoire. Ce répertoire doit être exclu du contrôle de version Git du référentiel principal pour éviter de suivre le contenu du sous-dépôt :

# Exclude all sub-repositories
repos/

3. Ajouter le référentiel parent à HagiCode

Si vous utilisez l’application de bureau HagiCode, ouvrez l’application et ajoutez votre référentiel principal en tant que projet. Cliquez sur le bouton « Ajouter un projet » ou « + » sur l’écran d’accueil, sélectionnez votre dossier de référentiel principal et vous verrez tous les sous-dépôts et leurs informations d’état.

4. Cloner des sous-dépôts

Utilisez le monospecs.yaml configuration pour cloner tous les sous-dépôts configurés vers le repos/ répertoire :

Cela clonera tous les sous-dépôts en fonction des URL spécifiées dans le fichier de configuration.

Structure du fichier de configuration

Configuration au niveau racine

version: "1.0"
commit_when_archive: true

repositories:
  # ... repository configurations

Configuration au niveau du référentiel

Chaque sous-référentiel peut avoir :

• Dossier de changement OpenSpec (openspec/)
• Indépendant .git/ répertoire
• Facultatif AGENTS.md pour la configuration de l’agent IA

Opérations de gestion du référentiel

Ajouter un nouveau référentiel

Lors de l’ajout d’un nouveau sous-référentiel au monospecs.yaml repositories tableau :

repositories:
  - path: "repos/new-service"
    url: "https://github.com/HagiCode-org/new-service.git"
    displayName: "New Service"
    icon: "🆕"

Mettre à jour la configuration du référentiel

Lorsque les URL ou les métadonnées du référentiel changent :

1. Modifier monospecs.yaml pour mettre à jour les entrées correspondantes
2. Vérifiez que la syntaxe YAML est correcte
3. En cas de synchronisation des modifications, mettez à jour manuellement la configuration du référentiel local

Prise en charge de la configuration des agents IA

AGENTS.md

Le AGENTS.md Le fichier fournit des conseils spécifiques au référentiel pour l’agent AI :

Informations sur la pile technique

• Framework et outils de construction
• Conventions de code et pratiques de dénomination
• Gestion des versions et configuration du déploiement

Comportements spécifiques au projet

• Extensions de configuration et exigences particulières
• Modèles d’intégration OpenSpec
• Besoins de coordination entre référentiels

Avantages de l’IA

Utilisation AGENTS.md permet à l’agent IA de :

• Comprendre les relations et les dépendances des référentiels
• Générez du code et refactorisez sur plusieurs référentiels
• Maintenir la cohérence dans le contrôle des versions et les configurations

Intégration OpenSpec

Comment fonctionne MonoSpecs avec OpenSpec

Qu’il s’agisse de gérer un projet géré monospecs ou un référentiel standard, vous pouvez utiliser le workflow OpenSpec de HagiCode :

Dépôt régulier :

• OpenSpec à la racine openspec/ répertoire
• Les modifications n’affectent que le référentiel actuel

Projet géré MonoSpecs :

• Lectures OpenSpec monospecs.yaml configuration
• Modifications suivies par sous-référentiel
• Spécifications automatiquement validées pour corriger les cibles

Comportement des archives

Quand commit_when_archive: true:

• Les spécifications sont automatiquement validées dans le référentiel principal
• Le code des sous-dépôts n’est pas validé (reste séparé)
• Simplifie la gestion des spécifications - aucun engagement de spécification manuel n’est nécessaire pour les sous-dépôts

Validations manuelles du sous-référentiel

Les sous-dépôts maintiennent un contrôle de version indépendant :

• Valider les modifications de code réelles dans leurs propres référentiels
• Les spécifications sont validées séparément (à partir du référentiel principal lors de l’archivage)

Meilleures pratiques

Conventions de dénomination des référentiels

• Utilisez la casse kebab (lettres minuscules et tirets) pour les chemins du référentiel
• Utilisez des noms d’affichage simples et descriptifs en chinois
• Utilisez des émojis pertinents comme icônes

Directives relatives au nom d’affichage

• Soyez concis et descriptif
• Utiliser une dénomination cohérente dans des référentiels similaires
• Sélectionnez des icônes qui représentent l’objectif du référentiel

Maintenance des configurations

Configuration de synchronisation avec l’état réel

• Vérifiez régulièrement monospecs.yaml reflète la structure réelle du référentiel
• Mettre à jour ou supprimer des entrées lorsque des référentiels sont ajoutés ou supprimés
• Tester les modifications pour garantir la validité de la configuration

Contrôle de version pour la configuration

• Suivre les modifications du fichier de configuration avec git
• Documenter les raisons des modifications majeures de la configuration
• Baliser les versions des fichiers de configuration pour une restauration facile

Dépannage

Fichier de configuration introuvable

Si le monospecs.yaml le fichier est introuvable à la racine du projet :

1. Vérifiez si le fichier existe au bon emplacement
2. Vérifiez que vous êtes dans le bon répertoire de travail
3. Vérifiez les fautes de frappe dans le nom du fichier de configuration

Erreurs de syntaxe YAML

Problèmes courants de syntaxe YAML :

• Indentation incorrecte (utilisez des espaces, pas des tabulations)
• Guillemets manquants ou supplémentaires autour des chaînes
• Types de données non valides (les chaînes nécessitent des guillemets, pas les nombres)
• Champs obligatoires manquants (comme path ou url)

Référentiel non détecté

Si un référentiel nouvellement ajouté n’apparaît pas :

1. Vérifiez le path est correct dans monospecs.yaml
2. Vérifiez que le référentiel a été cloné avec succès
3. Vérifiez si le référentiel existe à l’emplacement prévu

Échecs de clonage

Si le clonage du référentiel échoue :

1. Vérifier la connexion réseau
2. Vérifiez que l’URL du référentiel Git est correcte
3. Vérifier les problèmes d’authentification
4. Vérifier l’état du conteneur Docker
5. Vérifier la disponibilité de l’espace disque

---

Pour des informations plus détaillées, reportez-vous à la documentation monospecs et consultez le référentiel HagiCode pour des exemples de configuration.