Contribuer

Le guide de contribution de référence se trouve dans CONTRIBUTING.md, à la racine du dépôt, où GitHub le présente lors de la création d’issues et de pull requests. Cette page donne un bref aperçu ; le fichier à la racine fait autorité.

Comment les contributions parviennent au package#

hve-squad est distribué via APM sous forme de contenu de package à sens unique : les utilisateurs récupèrent le package, et celui-ci ne lit jamais leurs environnements. La seule voie permettant à un changement de parvenir au package publié consiste à créer un fork et à soumettre une pull request au dépôt.

1. Créez un fork du dépôt.
2. Créez une branche pour votre changement.
3. Ajoutez un fragment de changement avec apm run change.
4. Ouvrez une pull request vers la branche par défaut.
5. Un mainteneur effectue la revue, demande des modifications si nécessaire, puis fusionne.

Les utilisateurs reçoivent le changement fusionné à la prochaine exécution de apm run sync-deps.

Enregistrer votre changement#

Ne modifiez pas CHANGELOG.md et n’incrémentez pas version: dans apm.yml. Ce sont deux sorties de publication, assemblées sur la branche par défaut lors de la préparation d’une version, et la CI rejette toute pull request qui touche à l’une ou à l’autre.

La raison est mécanique. La version occupe une seule ligne et le titre le plus récent du changelog une seule position : deux pull requests qui les modifient entrent donc toujours en conflit — et la seconde à être fusionnée réutilise silencieusement un numéro de version déjà pris par la première. À la place, chaque pull request ajoute un nouveau fichier dans .changes/unreleased/. Deux pull requests ajoutant deux fichiers de noms différents n’entrent jamais en conflit.

apm run change

Le script vous demande quatre éléments et écrit le fichier pour vous :

• Type — la section Keep a Changelog à laquelle appartient votre entrée : Added, Changed, Deprecated, Removed, Fixed ou Security.
• Bump — la manière dont la version doit évoluer. Ce niveau suit les idées, pas les artefacts : la plupart des changements relèvent donc de patch.
• Title — une courte formule, utilisée uniquement pour nommer le fichier.
• Entry — le texte du changelog lui-même, rédigé tel qu’il doit apparaître dans les notes de publication.

Choisir le niveau d’incrémentation#

Ajouter un agent ne justifie pas une version mineure. Ajouter le concept auquel cet agent appartient, oui. Dix agents au service d’une même idée déjà distribuée représentent dix correctifs, pas dix versions mineures. En cas de doute, choisissez patch — le mainteneur voit le niveau calculé dans le contrôle de la pull request et corrige la ligne avant la fusion ; relever le niveau coûte peu, alors qu’une version mineure accidentelle est définitive.

Vous obtenez un fichier tel que .changes/unreleased/20260804-roster-row-resolves-to-nothing.md :

---
bump: patch
type: Fixed
---

- **A roster Primary pointed at an agent hve-core no longer ships.** Repointed it to ...

Rédigez l’entrée sous forme de puces Markdown commençant par - , car l’étape de publication les copie telles quelles. Commencez par une phrase en gras qui nomme le problème, puis indiquez ce qui a changé, et enfin citez les chemins de fichiers entre accents graves. Incluez le fragment dans le commit avec le reste de votre changement. Un fragment par idée — une pull request qui traite deux sujets sans rapport ajoute deux fragments.

Fusionner votre pull request ne la publie pas. Le fragment attend dans .changes/unreleased/ avec tous les autres changements déjà fusionnés, et un mainteneur prépare une version lorsque ce lot est prêt — dans l’heure pour un correctif rapide, ou plus tard pour un changement qui nécessite davantage de tests. Entre-temps, la fusion est publiée dans la préversion glissante : votre changement peut donc être installé et testé en quelques minutes :

apm install "Peter-N91/hve-squad#v0.19.0-pre" --target copilot

Le tag exact figure sur la page Releases, avec la mention de préversion. Il s’agit d’un canal plutôt que d’un point fixe : le tag se déplace à chaque fusion et change de nom lorsqu’un fragment minor est intégré. Utilisez une version publiée épinglée pour tout ce dont vous dépendez. La référence complète du format se trouve dans .changes/README.md.

Publier un correctif sans publier tout le reste#

Une version livre un commit, pas une sélection de fragments. Le tag est créé à partir de la tête de branche : une version issue de la branche par défaut contient donc tout ce qui y a été fusionné, quoi qu’indique le CHANGELOG. Choisir les fragments à consommer modifie les notes de publication, pas le code. Il reste donc deux cas, et seul le second nécessite une procédure particulière.

La branche par défaut est publiable. Un mainteneur déclenche Release Prep et votre correctif est publié avec tous les autres changements en attente, dans une seule version. Si un fragment en attente demande minor, cette version est mineure — et elle contient quand même votre correctif : les utilisateurs le reçoivent donc. C’est presque toujours la bonne solution.

La branche par défaut contient un changement qui ne doit pas encore être publié. Une version issue de cette branche emporterait ce travail avec le correctif. Le correctif doit donc partir d’un endroit qui ne le contient pas : une branche de correctif créée à partir du dernier tag de version.

git switch --detach v0.14.0
git switch -c hotfix/v0.14.1
# apply the fix, then record it
apm run change            # Type: Fixed, Bump: patch
git push -u origin hotfix/v0.14.1

Un mainteneur déclenche ensuite Release Prep en définissant ref sur la branche de correctif. Le workflow assemble le CHANGELOG uniquement à partir des fragments de cette branche, incrémente apm.yml à 0.14.1 et crée le tag à partir de cette branche. La préversion glissante de la branche par défaut reste intacte, car le lot qu’elle décrit est toujours en attente. La branche de correctif est ensuite fusionnée en retour avec le label release-merge-back, qui autorise cette pull request à inclure l’état de publication déjà écrit par Release Prep.

Un correctif publié après une version supérieure ne lui prend pas le badge Latest : le workflow de publication compare les versions et ne l’attribue pas lorsque le tag est inférieur à la version actuellement considérée comme la plus récente.

Proposer un apprentissage partagé#

Un apprentissage partagé est une règle durable et largement applicable, découverte lors de l’utilisation de la squad, qui devrait aider tous les autres utilisateurs confrontés au même scénario. La mémoire active des agents reste toujours locale à chaque environnement utilisateur et n’est jamais promue automatiquement. La promotion passe délibérément par une pull request soumise à validation humaine ; cette revue protège contre l’empoisonnement de la mémoire, les fuites de données et la dérive du contexte.

Expurgez chaque entrée de ses données sensibles avant de la proposer :

• Retirez tous les secrets, jetons, informations d’identification et chaînes de connexion.
• Retirez les noms de clients, d’organisations et de personnes.
• Retirez les chemins absolus propres au dépôt et les URL internes.
• Généralisez les détails propres à la pile technique pour que l’apprentissage s’applique au-delà de son contexte d’origine.
• Confirmez que l’apprentissage est largement applicable à différents utilisateurs et scénarios.

Les apprentissages partagés sélectionnés sont distribués avec le package dans squad-src/.github/skills/squad/learnings/shared-learnings.md. Lorsqu’un apprentissage est propre aux projets d’une organisation, promouvez-le plutôt vers un dépôt interne au tenant. Les deux voies, ainsi que le modèle de structure squad-learnings-tenant, sont décrites dans Apprentissages partagés.