featurevisor/featurevisor

Que fait featurevisor ?

Vous aidez l'utilisateur avec Featurevisor, la gestion de fonctionnalités via Git. Un projet Featurevisor est un référentiel de définitions YAML (par défaut) ou JSON. Le CLI les vérifie (lint), les teste et construit des fichiers de données JSON statiques, que les applications évaluent localement via des SDK. Chaque tâche se situe sur l'un des deux côtés :

• Côté projet : création et interrogation de définitions (fonctionnalités, segments, attributs, variables globales, tests) et exécution du CLI featurevisor.
• Côté application : chargement des fichiers de données et évaluation via un SDK (@featurevisor/sdk, React, Vue ou un autre langage).

Ce skill couvre les deux aspects pour Featurevisor v4. L'index de la documentation se trouve à https://featurevisor.com/llms.txt, avec le texte complet à https://featurevisor.com/llms-full.txt. Récupérez-les lorsqu'un sujet n'est pas couvert par les références ci-dessous.

Connaissez votre public

Les ingénieurs, chefs de produit, marketeurs et les personnes qui décrivent ce qu'elles veulent sans connaître le YAML utilisent tous Featurevisor. Adaptez-vous :

• Traduisez l'intention. « Activez la bannière pour 10 % des utilisateurs néerlandais » est une règle de déploiement progressif. Faites vous-même la correspondance, puis rapportez le résultat en leurs termes : ce qui a changé, qui est concerné et ce qui se passe ensuite.
• Modifications courantes : augmentation d'un pourcentage, ajout d'une règle au-dessus de la règle générique, ajout d'une fonctionnalité, forcer une fonctionnalité pour l'assurance qualité (QA). Effectuez-les en toute confiance.
• Modifications risquées : renommer une clé de règle, changer bucketBy, modifier les pondérations des variations, réduire un pourcentage, archiver quelque chose qui est encore référencé. Ces actions déplacent des utilisateurs entre les résultats. Dites-le clairement (« certains utilisateurs perdraient la fonctionnalité en cours de session ») et confirmez avant de procéder.
• Bouclez la boucle. Après une modification, dites en une ou deux phrases ce qui se passe une fois qu'elle est déployée. Par exemple : « une fois que cette modification fusionnera et que le CI déploiera le fichier de données, environ 10 % des utilisateurs aux Pays-Bas verront la bannière, tous les autres ne verront rien. »
• Proposez le catalogue à quiconque souhaite voir le projet plutôt que de lire du YAML (Revue visuelle avec le catalogue).

Orientez-vous d'abord

Les exemples de ce skill utilisent la structure par défaut, qui n'a pas d'environnements. Lorsque le projet configure des environnements, ajoutez --environment=<nom> à evaluate, benchmark, assess-distribution et build --print. Une compilation de fichier normale couvre tous les environnements.

Pas encore de projet ? Interviewez, puis créez la structure

Sans featurevisor.config.js dans l'arborescence de travail, il n'y a pas de projet Featurevisor. Si l'utilisateur se trouve dans un référentiel d'application, il s'agit d'un travail de SDK : voir Intégration d'application (SDK) et créez les définitions dans le référentiel du projet, pas ici. S'ils veulent un nouveau projet, posez d'abord ces questions, car chaque fichier écrit par la suite en dépend :

1. Environnements ? La valeur par défaut n'en a pas, et les règles sont des listes directes. --example=with-environments donne des staging et production explicites.
2. Ensembles (Sets) ? Par défaut non. Proposez les Sets uniquement pour des arborescences examinées indépendamment : les lanes de release (branches de publication) promues de dev à staging à production, ou des surfaces sans rapport comme une vitrine et une administration. Lisez d'abord sets-promotions.md.
3. Consommateurs ? Une seule application peut utiliser la cible all par défaut, qui n'a pas de sélecteurs et inclut toutes les définitions actives. Plusieurs surfaces obtiennent généralement des balises telles que web, ios et android, et une cible par surface.
4. Format de fichier ? YAML (par défaut) ou JSON.
5. Qu'est-ce qui identifie un utilisateur ? userId, deviceId, ou les deux (bucketBy: { or: [userId, deviceId] }). Le linting exige bucketBy sur chaque fonctionnalité, donc cela détermine ce que chaque fonctionnalité déclare et quels attributs viennent en premier.

Créez la structure dans un répertoire vide, dans son propre référentiel, séparé du code de l'application :

npx @featurevisor/cli@latest init
npm install

--example=with-environments donne des règles avec clés d'environnement, --example=environments donne des Sets en tant que lanes de release, et --example=sets donne des surfaces indépendantes. Le tableau de configuration CLI liste chaque exemple. Ajoutez ensuite les réponses de l'interview à featurevisor.config.js. templates/example-project/ est un projet v4 complet qui passe le lint et les tests, utile comme référence pour comprendre comment les pièces s'assemblent.

Projet existant ? Détectez la version et la forme avant de toucher à quoi que ce soit

Confirmez que le projet a un @featurevisor/cli installé dans son manifeste de package et son fichier de verrouillage, et avec npm ls @featurevisor/cli. Exécutez ensuite le CLI installé depuis le projet :

npx featurevisor --version

Il doit résoudre le binaire propre au projet. S'il est manquant ou si npx propose de télécharger un package, arrêtez-vous et demandez à restaurer les dépendances verrouillées du projet. N'installez pas un CLI distant et ne mettez pas à niveau les dépendances juste pour détecter une version.

• 4.x : tout dans ce skill s'applique.
• 3.x : la syntaxe v3 diffère. Elle utilise segments dans les règles et requiredFeatures au lieu de conditions unifiées, et manque de conditions de variable, de compositions, de continue, de checks de test, de scénarios et de plusieurs opérateurs. N'écrivez pas de syntaxe v4 dans un projet v3. Restez dans ce que upgrading-to-v4.md liste comme syntaxe v3, et proposez la mise à niveau lorsque la demande nécessite la v4.
• 2.x : des formes telles que scopes:, un répertoire environments/ ou createInstance dans le code de l'application. Proposez d'abord upgrading-to-v3.md.

Les consommateurs décident ce que vous pouvez publier. Les fichiers de données v4 nécessitent des SDK v4 : les SDK v3 ne comprennent pas les conditions unifiées, donc les règles cessent de correspondre. Le schemaVersion du fichier de données est informatif et n'empêche pas un ancien SDK de rejeter le fichier. Avant d'introduire une capacité d'exécution telle que l'accumulation de remplacements ou un opérateur plus récent, confirmez la version du SDK de chaque application consommant ce fichier de données. Demandez à l'utilisateur lorsque ce n'est pas connu. Vérifiez chaque version par rapport à la matrice de compatibilité SDK. Les numéros de version natifs diffèrent, donc ne supposez pas que chaque SDK compatible est numéroté 4.x. Le succès du lint CLI seul n'établit pas la prise en charge à l'exécution. Les tests et scénarios nécessitent des exécuteurs CLI compatibles, ce qui est une question distincte de ce que les consommateurs prennent en charge.

Lisez ensuite la configuration :

npx featurevisor config --json --pretty
npx featurevisor info

Quatre valeurs modifient la forme de tout ce que vous écrivez :

• sets : lorsqu'il est true, chaque définition se trouve sous sets/<set>/ et les commandes prennent --set. Lisez d'abord sets-promotions.md.
• environments : lorsqu'il est déclaré, les rules, force et expose des fonctionnalités, et les overrides des variables globales, sont des cartes indexées par environnement. Sans cela, ce sont des listes directes, et expose est un booléen ou une liste de balises.
• parser : créez du JSON pour "json", du YAML pour "yml" (par défaut), ou le format personnalisé configuré (custom-parsers.md).
• namespaceCharacter : séparateur pour les clés provenant de sous-répertoires. Par défaut ., donc features/checkout/promo.yml est checkout.promo. Certains projets utilisent /. Chaque référence doit utiliser le séparateur du projet. Confirmez par rapport aux clés réelles avec npx featurevisor list --segments --json.

Notez également tags (chaque balise que vous utilisez doit être déclarée), disallowOperators, allowedConditions et les remplacements de répertoire tels que featuresDirectoryPath. Lisez ensuite une ou deux définitions existantes pour vous aligner sur le style local avant d'en ajouter de nouvelles.

Comment Featurevisor s'assemble

Définition	Chemin	Objectif
Attribut	attributes/<clé>.yml	Déclare une clé de contexte et son type. Jamais avec espace de noms.
Segment	segments/<clé>.yml	Nomme une audience via conditions.
Fonctionnalité	features/<clé>.yml	Un indicateur, des variations optionnelles et des variables de fonctionnalité, avec des règles de déploiement. Avec bucket.
Variable globale	variables/<clé>.yml	Une valeur typée avec des remplacements ordonnés, ou une compose d'autres valeurs. Jamais avec bucket.
Schéma	schemas/<clé>.yml	Une forme de variable réutilisable.
Cible	targets/<clé>.yml	Quelles définitions entrent dans un fichier de données.
Spécification de test	tests/**/*.spec.yml	Assertions sur les fonctionnalités, segments et variables, et scénarios autonomes.

Les conditions sont une grammaire unique utilisée partout où une définition sélectionne ou verrouille : segments, règles, entrées de forçage, verrous racine et remplacements. Une feuille compare un attribut, nomme un segment avec une chaîne nue, nécessite une fonctionnalité ou compare la valeur d'une variable. Une liste signifie ET, et les groupes and, or et not s'imbriquent. '*' correspond à tout le monde, mais seulement en tant qu'expression entière.

conditions:
  - attribute: country
    operator: equals
    value: nl
  - payingAccounts # une chaîne nue est toujours une clé de segment
  - feature: liveChat # nécessite que liveChat soit activé
  - variable: maintenanceMode
    operator: equals
    value: false

Ordre d'évaluation. L'indicateur d'une fonctionnalité vérifie une valeur persistante, puis si la fonctionnalité est dans le fichier de données, puis la première entrée de forçage correspondante, puis les conditions racine, puis la première règle dont les conditions correspondent, et enfin le pourcentage de cette règle par rapport au bucket de l'utilisateur. Un échec de pourcentage ne retombe pas sur la règle suivante. Une variable globale vérifie une valeur persistante, puis les conditions racine, puis les sources de composition le cas échéant, puis le premier remplacement correspondant (et les suivants également lorsqu'un remplacement définit continue: true), puis sa valeur par défaut. Détails : features.md et global-variables.md.

Règles fondamentales de création

Les références ajoutent de la profondeur, mais elles ne remplacent jamais ces règles.

1. Le bucketing et les clés de règle sont des contrats

• bucketBy maintient le résultat de chaque utilisateur stable pendant que les pourcentages changent. Choisissez-le une fois et ne le modifiez jamais silencieusement.
• Les surfaces connectées buckétisent par userId, les surfaces anonymes par deviceId, les surfaces mixtes par { or: [userId, deviceId] }. Les noms d'attributs varient entre les projets : lisez attributes/ et demandez lesquels utiliser lorsque ce n'est pas évident. N'inventez jamais de noms d'attributs.
• Les clés de règle doivent être uniques par liste (par environnement lorsqu'il est configuré) et ne doivent pas changer une fois que les utilisateurs sont placés dans des buckets. Les fichiers d'état stockent les plages de variation de chaque règle par clé, donc un renommage les réalloue. Ajoutez une nouvelle règle au lieu de renommer.

2. La première règle correspondante gagne

Les règles sont exécutées de haut en bas. Placez les règles étroites, comme un pays à 100 %, au-dessus de la règle générique conditions: '*'. Une fois qu'une règle correspond, son pourcentage décide, et les utilisateurs au-dessus ne retombent pas sur les règles suivantes.

3. Ne référencez que ce qui existe

Confirmez que chaque attribut, segment, fonctionnalité et variable que vous référencez existe, ou créez-le. Vérifiez également allowedConditions dans featurevisor.config.js : il peut limiter les types de conditions que chaque emplacement accepte, par exemple les règles qui ne nomment que des segments (conditions.md). Le lint rejette les références inconnues. Il rejette également, avec archived_reference, toute référence à une définition archivée à partir d'une définition ou d'une spécification qui n'est pas elle-même archivée. Une définition archivée est retirée des fichiers de données, donc une référence à celle-ci cesserait silencieusement de correspondre, et sous not correspondrait à tout le monde. Le lint vérifie les définitions archivées uniquement pour leur forme, donc ce qu'elles utilisaient peut ensuite changer ou disparaître. Une référence à une définition obsolète est un avertissement deprecated_reference. Exécutez npx featurevisor find-usage avant d'archiver, renommer ou supprimer quoi que ce soit, et préférez l'archivage à la suppression : le fichier archivé réserve la clé.

4. Les pondérations des variations totalisent 100

Chaque valeur est unique. control et treatment ne sont que des conventions. Le lint rejette les pondérations qui ne totalisent pas 100. Avec le CLI 4.0.0, ce n'était pas le cas, donc vérifiez vous-même la somme : une répartition courte compile une fois, puis chaque compilation ultérieure échoue avec Invalid saved variation allocation. Pour les expériences mutuellement exclusives, voir mutual-exclusion.md.

5. Les conditions restent portables entre les SDK

Chaque SDK évalue le même fichier de données, donc le lint impose un sous-ensemble portable :

• Dates (before, after) prennent un horodatage ISO 8601 complet avec un fuseau horaire, entre guillemets : '2026-11-27T00:00:00Z'. Les valeurs sans date ou sans fuseau horaire échouent au lint. Les deux opérateurs sont stricts.
• Versions (semver*) sont des chaînes entre guillemets telles que '5.5' ou '5.5.0', donc YAML les conserve sous forme de texte.
• Expressions régulières (matches, notMatches) autorisent uniquement les indicateurs g, i, m et s, et rejettent toute construction (?, y compris les groupes non capturants (?:…), les références arrière et les quantificateurs possessifs.
• Les opérateurs sont vérifiés par rapport aux types déclarés. Un attribut type: string avec format: date-time ne prend que les opérateurs before, after et de présence, et in prend une liste de chaînes.

Détails et messages de lint : operators.md.

6. Adaptez-vous à la forme du projet

Les environnements, les ensembles, l'analyseur syntaxique et le séparateur d'espace de noms modifient la façon dont la même demande est écrite. Les modèles utilisent la forme par défaut sans environnements. Dans un projet avec environnements, placez chaque liste rules, force ou overrides globaux sous sa clé d'environnement, et ajoutez environment aux tests.

Définition de fait

Exécutez cette boucle après chaque modification. C'est ainsi que vous prouvez qu'une modification fait ce que l'utilisateur a demandé, et cela vous donne les preuves pour faire un rapport.

1. Lint. npx featurevisor lint doit passer. Avec --json, chaque erreur a filePath, path, message et code, donc vous pouvez corriger le champ exact. Relancez après correction : certaines erreurs n'apparaissent qu'une fois les précédentes résolues.

...

[le contenu est tronqué pour la traduction]