From e82a7ab5f3b998526320127130fd427d07d73900 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 15:13:50 +0000 Subject: [PATCH 01/10] docs: remove the server component from the privacy policy and the store listing The verifier was removed from the product (DEC0010), but three documents still described it: the privacy policy carried a whole section on an optional self-hosted server component, the store listing drafts promised merge enforcement through it, and the setup guides announced it as what comes next. - PRIVACY.md: the scope paragraph says the extension is the whole product, the server section is gone, in French and in English - PRIVACY.md: the synced preferences also include the label button order, and the platforms named are GitHub, Azure DevOps and GitLab - store listing drafts: the organisation paragraph describes the enterprise policy, and says the extension does not control merging - setup guides: the closing line points at the user guide Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_019k6GsTjvs6iTePictnANBu --- PRIVACY.md | 103 +++++++------------------------------ docs/extension-setup-en.md | 4 +- docs/extension-setup-fr.md | 4 +- docs/store-listing-en.md | 11 ++-- docs/store-listing-fr.md | 12 ++--- 5 files changed, 35 insertions(+), 99 deletions(-) diff --git a/PRIVACY.md b/PRIVACY.md index 01075164..701be184 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -1,6 +1,6 @@ # Politique de confidentialité — Conventional Comments Toolkit -_Dernière mise à jour : 2026-11-11._ +_Dernière mise à jour : 2026-11-12._ Cette page sert de politique de confidentialité publique pour l'extension navigateur **Conventional Comments Toolkit**, distribuée sur le Chrome Web @@ -13,21 +13,18 @@ Résumé en une phrase : **l'extension elle-même ne collecte, ne stocke sur un serveur distant, ni ne transmet aucun contenu de code, de commentaire ou de diff que vous consultez ou rédigez.** -**Périmètre de ce document.** Le tableau ci-dessous couvre exclusivement -l'**extension navigateur** — c'est elle qui est distribuée sur les stores -et pour laquelle ce document sert de politique de confidentialité -publique. Le produit inclut aussi un **composant serveur optionnel**, -auto-hébergé et exploité par chaque organisation qui choisit de le -déployer (§10, §14 de la spécification) : voir la section dédiée plus bas -plutôt que le tableau, qui ne l'engloble pas champ par champ — c'est un -composant à la surface de persistance propre, sous le contrôle de -l'organisation qui l'exploite, pas de l'éditeur de l'extension. +**Périmètre de ce document.** Le produit est l'extension navigateur, et +elle seule : il ne comporte aucun composant serveur. Une rédaction +antérieure de cette page décrivait un composant serveur optionnel, +auto-hébergé par chaque organisation ; il a été retiré du produit +([DEC0010](docs/idr/DEC0010-the-extension-is-the-whole-product-fr.md)), +et la section qui le décrivait avec lui. ## Ce que l'extension fait Conventional Comments Toolkit assiste la rédaction de commentaires de -revue de code conformes à la convention Conventional Comments, sur GitHub -et, en option, Azure DevOps : barre d'outils d'insertion de labels, +revue de code conformes à la convention Conventional Comments, sur GitHub, +Azure DevOps et GitLab : barre d'outils d'insertion de labels, validation du format à la saisie, retour visuel dans l'éditeur natif de la plateforme. @@ -35,7 +32,7 @@ plateforme. | Donnée | Où elle vit | Sort-elle du navigateur ? | |---|---|---| -| Langue d'interface et raccourcis clavier directs | `chrome.storage.sync` | **Se synchronise entre les appareils de votre compte Chrome si la synchronisation est activée** — c'est le mécanisme natif de Chrome, pas un serveur propre à l'extension. Contenu limité à ces deux préférences, jamais de contenu de commentaire ou de code. | +| Langue d'interface, raccourcis clavier directs et ordre des boutons de label | `chrome.storage.sync` | **Se synchronise entre les appareils de votre compte Chrome si la synchronisation est activée** — c'est le mécanisme natif de Chrome, pas un serveur propre à l'extension. Contenu limité à ces trois préférences, jamais de contenu de commentaire ou de code. | | État dégradé courant (diagnostic) | `chrome.storage.local`, sur votre appareil | Non | | Avis de la dernière lecture de configuration (affichés dans la page d'options) : l'hôte et le chemin du dépôt lu (par exemple `github.com/organisation/depot`), et pour chaque avis sa sorte, son code, son texte en anglais et ce qu'il cite — clé ou valeur de configuration, numéro et extrait borné (40 caractères) d'un motif d'allowlist, version, niveau en cause —, plus, en référence, la **valeur rejetée elle-même, en entier** : motif d'allowlist ou commande d'outil, tels qu'écrits dans la configuration. Remplacés à chaque lecture, sans historique | `chrome.storage.local`, sur votre appareil | Non | | Domaines optionnels activés (Azure DevOps, GitHub Enterprise, etc.) | `chrome.permissions`, géré par Chrome | Non — c'est Chrome, pas l'extension, qui tient cette liste | @@ -51,36 +48,6 @@ ne s'authentifie auprès d'aucune API à jeton : les seules données qu'elle lit hors du DOM de la page sont celles accessibles par la route web déjà autorisée par votre session de navigation. -## Composant serveur optionnel (auto-hébergé par votre organisation) - -**Non requis pour utiliser l'extension.** Une organisation peut déployer -ce composant pour faire respecter la convention comme condition de -fusion des pull requests, avec un mécanisme d'exemption gouverné. S'il -est déployé, il persiste — sur l'infrastructure de l'organisation, pas -sur un service tiers de l'éditeur de l'extension — des catégories de -données propres à son fonctionnement, entre autres : -- le journal et l'état actif des exemptions de PR (identifiant de PR, - action, personne à l'origine, horodatage, et **un motif en texte libre - si la personne en saisit un** — susceptible de contenir des - informations personnelles ou sensibles) ; -- des enregistrements d'évaluation de conformité par PR, qui incluent un - **court extrait** (jusqu'à ~80 caractères) du commentaire racine de - chaque fil bloquant non résolu, avec l'identifiant de son auteur ; -- des compteurs d'usage agrégés par dépôt et par PR (répartition des - labels, nombre de fils non résolus, etc.), **indépendants du réglage - `telemetry.enabled`** de l'extension — ce sont deux mécanismes - distincts ; -- un état opérationnel courant (configuration en cache, séquencement des - publications, alias de chemin de PR) nécessaire au fonctionnement du - composant. - -**Cette liste illustre les catégories, elle n'est pas exhaustive et n'a -pas vocation à l'être** : le code de ce composant évolue, et une -organisation qui le déploie en est l'opérateur au sens du RGPD (ou du -cadre équivalent) — c'est à elle, pas à ce document, de fournir la -politique de confidentialité applicable à ses utilisateurs pour cette -instance, avec sa propre destination et durée de conservation. - ## Permissions et pourquoi Le détail permission par permission (`storage`, `scripting`, @@ -116,7 +83,7 @@ Pour toute question sur cette politique de confidentialité, ouvrez une # Privacy Policy — Conventional Comments Toolkit -_Last updated: 2026-11-11._ +_Last updated: 2026-11-12._ This page is the public privacy policy for the **Conventional Comments Toolkit** browser extension, distributed on the Chrome Web Store and @@ -128,28 +95,25 @@ One-sentence summary: **the extension itself does not collect, store on a remote server, or transmit any code, comment, or diff content you view or write.** -**Scope of this document.** The table below covers the **browser -extension** only — that's what's distributed on the stores and what this -document serves as the public privacy policy for. The product also -includes an **optional server component**, self-hosted and operated by -each organization that chooses to deploy it (§10, §14 of the functional -spec): see the dedicated section below instead of the table, which -doesn't try to enumerate it field by field — it's a component with its -own persistence surface, under the control of the organization running -it, not of the extension's publisher. +**Scope of this document.** The product is the browser extension, and +only the extension: it has no server component. An earlier version of +this page described an optional server component, self-hosted by each +organization; it was removed from the product +([DEC0010](docs/idr/DEC0010-the-extension-is-the-whole-product-en.md)), +and the section describing it went with it. ## What the extension does Conventional Comments Toolkit assists writing code review comments that -follow the Conventional Comments convention, on GitHub and, optionally, -Azure DevOps: a toolbar for inserting labels, input validation, and +follow the Conventional Comments convention, on GitHub, Azure DevOps +and GitLab: a toolbar for inserting labels, input validation, and visual feedback inside the platform's native comment editor. ## Data processed by the browser extension | Data | Where it lives | Does it leave the browser? | |---|---|---| -| Interface language and direct keyboard shortcuts | `chrome.storage.sync` | **Syncs across your Chrome account's devices if sync is enabled** — that's Chrome's own native mechanism, not a server run by the extension. Limited to these two preferences, never comment or code content. | +| Interface language, direct keyboard shortcuts and label button order | `chrome.storage.sync` | **Syncs across your Chrome account's devices if sync is enabled** — that's Chrome's own native mechanism, not a server run by the extension. Limited to these two preferences, never comment or code content. | | Current degraded state (diagnostics) | `chrome.storage.local`, on your device | No | | Notices from the last configuration read (shown in the options page): the host and path of the repository read (for example `github.com/organization/repository`), and for each notice its kind, its code, its English text and what it cites — a configuration key or value, the index and a bounded excerpt (40 characters) of an allowlist pattern, a version, the level at fault —, plus, as a reference, **the rejected value itself, in full**: an allowlist pattern or a tool command, as written in the configuration. Replaced at each read, with no history | `chrome.storage.local`, on your device | No | | Enabled optional domains (Azure DevOps, GitHub Enterprise, etc.) | `chrome.permissions`, managed by Chrome | No — Chrome holds this list, not the extension | @@ -165,33 +129,6 @@ authenticate against any token-based API: the only data it reads outside the page DOM is what is reachable via the web route your browsing session already authorizes. -## Optional server component (self-hosted by your organization) - -**Not required to use the extension.** An organization may deploy this -component to enforce the convention as a merge requirement for pull -requests, with a governed exemption mechanism. If deployed, it persists -— on the organization's own infrastructure, not a third-party service run -by the extension's publisher — categories of data specific to its -operation, including but not limited to: -- the PR exemption log and active-exemption state (PR id, action, actor, - timestamp, and **a free-text reason if one was entered** — potentially - containing personal or sensitive information); -- compliance-evaluation records per PR, which include a **short excerpt** - (up to ~80 characters) of the root comment of each unresolved blocking - thread, along with its author's identifier; -- aggregated usage counters per repository and PR (label distribution, - unresolved-thread counts, etc.), **independent of the extension's - `telemetry.enabled` setting** — these are two distinct mechanisms; -- operational state (cached configuration, publication sequencing, PR - path aliases) needed for the component to function. - -**This list illustrates categories; it is not exhaustive and isn't meant -to be** — the code of this component evolves, and an organization that -deploys it is the operator, under GDPR or an equivalent framework: it is -that organization's responsibility, not this document's, to provide the -applicable privacy policy to its own users for that deployment, with its -own destination and retention terms. - ## Permissions and why A permission-by-permission breakdown (`storage`, `scripting`, diff --git a/docs/extension-setup-en.md b/docs/extension-setup-en.md index 7458feb4..51e259eb 100644 --- a/docs/extension-setup-en.md +++ b/docs/extension-setup-en.md @@ -190,5 +190,5 @@ extension's settings page from any tab, without going back through field. If all of that works, the extension is up and running. It operates in `assist` mode by -default — it helps and flags issues, but never blocks submission (see `A-FAIRE-fr.md` at -the repository root for what's next: the server component, other platforms, etc.). +default — it helps and flags issues, but never blocks submission (see the [user guide](README-en.md) +for everything it does, and `A-FAIRE-fr.md` at the repository root for what remains to be done). diff --git a/docs/extension-setup-fr.md b/docs/extension-setup-fr.md index a7e48c0f..7714b0f3 100644 --- a/docs/extension-setup-fr.md +++ b/docs/extension-setup-fr.md @@ -198,5 +198,5 @@ n'importe quel onglet, sans repasser par `chrome://extensions`. le champ. Si tout ça fonctionne, l'extension est opérationnelle. Elle tourne en mode `assist` par -défaut — elle aide et signale, mais ne bloque jamais l'envoi (voir `A-FAIRE-fr.md` à la -racine du dépôt pour la suite : composant serveur, autres plateformes, etc.). +défaut — elle aide et signale, mais ne bloque jamais l'envoi (voir le [guide utilisateur](README-fr.md) +pour tout ce qu'elle fait, et `A-FAIRE-fr.md` à la racine du dépôt pour ce qui reste à faire). diff --git a/docs/store-listing-en.md b/docs/store-listing-en.md index ce47d63a..c77d1e4c 100644 --- a/docs/store-listing-en.md +++ b/docs/store-listing-en.md @@ -39,9 +39,8 @@ guarantee, which does hold unconditionally. > doesn't follow the convention. > - A keyboard-driven quick-input mode for people who'd rather not touch > the mouse. -> - Works standalone, no backend required: the extension assists and -> validates even without the optional team-governance server -> component. +> - Works standalone, with no server at all: the extension is the whole +> product. > > **Privacy by design** > No comment, code, or diff content ever leaves your browser. No @@ -53,9 +52,9 @@ guarantee, which does hold unconditionally. > https://github.com/reefact/conventional-comments-toolkit/blob/main/PRIVACY.md > > **For organizations** -> An optional server component (not required to use the extension) lets -> teams enforce the convention as a merge requirement for pull requests, -> with a governed and auditable exemption mechanism. +> A shared configuration and a floor of rules can be pushed through the +> browser's enterprise policy. The extension reports unresolved blocking +> threads; it does not control the merging of pull requests. > > Public source code under the Apache-2.0 license: > https://github.com/reefact/conventional-comments-toolkit diff --git a/docs/store-listing-fr.md b/docs/store-listing-fr.md index 9b661116..3030b697 100644 --- a/docs/store-listing-fr.md +++ b/docs/store-listing-fr.md @@ -44,9 +44,8 @@ contenu, qui elle tient sans condition. > un commentaire ne respecte pas la convention. > - Une saisie rapide au clavier pour les personnes qui préfèrent ne pas > toucher la souris. -> - Un fonctionnement autonome, sans backend requis : l'extension assiste -> et valide même sans le composant serveur optionnel de gouvernance -> d'équipe. +> - Un fonctionnement autonome, sans aucun serveur : l'extension est tout +> le produit. > > **Confidentialité par conception** > Aucun contenu de commentaire, de code ou de diff ne quitte votre @@ -58,9 +57,10 @@ contenu, qui elle tient sans condition. > https://github.com/reefact/conventional-comments-toolkit/blob/main/PRIVACY.md > > **Pour les organisations** -> Un composant serveur optionnel (non requis pour utiliser l'extension) -> permet de faire respecter la convention comme condition de fusion des -> pull requests, avec un mécanisme d'exemption gouverné et traçable. +> Une configuration partagée et un plancher de règles peuvent être +> poussés par la politique d'entreprise du navigateur. L'extension +> signale les fils bloquants non résolus ; elle ne contrôle pas la +> fusion des pull requests. > > Code source public sous licence Apache-2.0 : > https://github.com/reefact/conventional-comments-toolkit From 1d75cda9317aaf6a3b820dde38a57f3cdb2d8436 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 15:13:50 +0000 Subject: [PATCH 02/10] docs: add a user guide and rewrite the README around the reader MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README described the repository to its maintainers: layout, CI, phases of the specification. Nothing told someone who installs the extension what it does, how to allow a platform, what a diagnostic means or which shortcuts exist; the list of direct shortcuts lived only in the code. - README.md, README-fr.md: the problem, the solution with images, install, platforms, what the extension is and is not, and a documentation table - docs/guide/: twelve pages, each in English and French — getting started, writing comments, keyboard input, labels, diagnostics, configuration, modes and adoption, organisation deployment, platforms, settings page, FAQ, review skills - docs/README-en.md, docs/README-fr.md: the documentation index - docs/development-en.md: what the README held for maintainers (layout, commands, CI, status against the phases), unchanged in substance - CONTRIBUTING.md: the repository's rules in short, with their IDRs - docs/images/, scripts/doc-screenshots.mjs, npm run docs:screenshots: the toolbar, the pill and the badges rendered by the shipped components in Chromium, on a test page; the captions say they are not screenshots of github.com The macOS limit of the Alt shortcuts is documented as not measured: the code compares KeyboardEvent.key, which Option+letter changes on a Mac. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_019k6GsTjvs6iTePictnANBu --- A-FAIRE-fr.md | 3 +- CONTRIBUTING.md | 68 +++++ README-fr.md | 198 +++++++++++++ README.md | 422 +++++++++++----------------- docs/README-en.md | 77 +++++ docs/README-fr.md | 78 +++++ docs/development-en.md | 117 ++++++++ docs/guide/configuration-en.md | 290 +++++++++++++++++++ docs/guide/configuration-fr.md | 298 ++++++++++++++++++++ docs/guide/diagnostics-en.md | 83 ++++++ docs/guide/diagnostics-fr.md | 87 ++++++ docs/guide/faq-en.md | 121 ++++++++ docs/guide/faq-fr.md | 129 +++++++++ docs/guide/getting-started-en.md | 92 ++++++ docs/guide/getting-started-fr.md | 98 +++++++ docs/guide/keyboard-input-en.md | 147 ++++++++++ docs/guide/keyboard-input-fr.md | 152 ++++++++++ docs/guide/labels-en.md | 165 +++++++++++ docs/guide/labels-fr.md | 166 +++++++++++ docs/guide/modes-and-adoption-en.md | 96 +++++++ docs/guide/modes-and-adoption-fr.md | 99 +++++++ docs/guide/organization-en.md | 128 +++++++++ docs/guide/organization-fr.md | 132 +++++++++ docs/guide/platforms-en.md | 85 ++++++ docs/guide/platforms-fr.md | 88 ++++++ docs/guide/review-skills-en.md | 59 ++++ docs/guide/review-skills-fr.md | 62 ++++ docs/guide/settings-en.md | 72 +++++ docs/guide/settings-fr.md | 76 +++++ docs/guide/writing-comments-en.md | 157 +++++++++++ docs/guide/writing-comments-fr.md | 160 +++++++++++ docs/images/badges-en.png | Bin 0 -> 71175 bytes docs/images/badges-fr.png | Bin 0 -> 75045 bytes docs/images/diagnostic-en.png | Bin 0 -> 103493 bytes docs/images/diagnostic-fr.png | Bin 0 -> 107539 bytes docs/images/toolbar-en.png | Bin 0 -> 90967 bytes docs/images/toolbar-fr.png | Bin 0 -> 95930 bytes package.json | 1 + scripts/doc-screenshots.mjs | 146 ++++++++++ 39 files changed, 3890 insertions(+), 262 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 README-fr.md create mode 100644 docs/README-en.md create mode 100644 docs/README-fr.md create mode 100644 docs/development-en.md create mode 100644 docs/guide/configuration-en.md create mode 100644 docs/guide/configuration-fr.md create mode 100644 docs/guide/diagnostics-en.md create mode 100644 docs/guide/diagnostics-fr.md create mode 100644 docs/guide/faq-en.md create mode 100644 docs/guide/faq-fr.md create mode 100644 docs/guide/getting-started-en.md create mode 100644 docs/guide/getting-started-fr.md create mode 100644 docs/guide/keyboard-input-en.md create mode 100644 docs/guide/keyboard-input-fr.md create mode 100644 docs/guide/labels-en.md create mode 100644 docs/guide/labels-fr.md create mode 100644 docs/guide/modes-and-adoption-en.md create mode 100644 docs/guide/modes-and-adoption-fr.md create mode 100644 docs/guide/organization-en.md create mode 100644 docs/guide/organization-fr.md create mode 100644 docs/guide/platforms-en.md create mode 100644 docs/guide/platforms-fr.md create mode 100644 docs/guide/review-skills-en.md create mode 100644 docs/guide/review-skills-fr.md create mode 100644 docs/guide/settings-en.md create mode 100644 docs/guide/settings-fr.md create mode 100644 docs/guide/writing-comments-en.md create mode 100644 docs/guide/writing-comments-fr.md create mode 100644 docs/images/badges-en.png create mode 100644 docs/images/badges-fr.png create mode 100644 docs/images/diagnostic-en.png create mode 100644 docs/images/diagnostic-fr.png create mode 100644 docs/images/toolbar-en.png create mode 100644 docs/images/toolbar-fr.png create mode 100644 scripts/doc-screenshots.mjs diff --git a/A-FAIRE-fr.md b/A-FAIRE-fr.md index 7169f3ad..41156dc4 100644 --- a/A-FAIRE-fr.md +++ b/A-FAIRE-fr.md @@ -133,7 +133,8 @@ du pilote en `enforce` (2c). Les autres sont des ## 5. Où trouver le reste -- `README.md` — vue d'ensemble, commandes, statut par phase (§14). +- `README.md` — présentation du produit ; `docs/README-fr.md` — index de la documentation, + guide utilisateur compris ; `docs/development-en.md` — commandes, CI, statut par phase (§14). - `docs/architecture-fr.md` — la découpe en paquets et ce que `core/` garantit. - `docs/operations-fr.md` — trajectoire, prérequis avant `enforce`, procédure de retour arrière. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..1003793b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing + +Issues and pull requests are welcome. This page is the short version of the repository's +rules; the full text is [`CLAUDE.md`](CLAUDE.md) (in French), and the reasons behind each rule +are recorded in [`docs/idr/`](docs/idr/README-en.md). + +## Reporting a problem + +Open an [issue](https://github.com/reefact/conventional-comments-toolkit/issues). When the +extension does not show up or misbehaves on a page, attach the diagnostic archive: settings +page → *Status* → **Download the diagnostic (.zip)**. + +**Read `report.json` before attaching it.** It holds no comment, code or field text, but page +addresses name repositories and pull requests, and an interface label can name an account. + +Diagnostic reports are collected as issues and fixed in batches rather than one by one, so +that a fix for one page does not break another +([DEC0006](docs/idr/DEC0006-diagnostic-reports-as-issues-en.md)). + +## Setting up + +``` +npm install +npm test +npm run build +npm run checks +``` + +Commands that question the browser need Chromium once per machine: +`npx playwright-core install chromium`. See [`docs/development-en.md`](docs/development-en.md) +for the layout, the commands and the continuous integration. + +## Rules of a pull request + +- **Language.** Commit messages, pull request titles, bodies and review comments are in + English. Code comments are in French. Repository documents are in English, with a French + twin (`-en.md` / `-fr.md`) when possible + ([DEC0002](docs/idr/DEC0002-english-first-language-follows-the-reader-en.md)). +- **One platform, or the shared code, never both.** A pull request touches one platform + adapter, or the code they share; one that would do both is split, the shared change first + ([DEC0005](docs/idr/DEC0005-one-platform-per-pull-request-en.md)). `npm run check:pr-scope` + checks it, and CI runs it. +- **The specification is normative.** [`specifications-fr.md`](specifications-fr.md) is never + edited to match the implementation. A pull request may amend it together with the code that + implements the amendment: that is a design decision, and it says so + ([DEC0004](docs/idr/DEC0004-spec-amendments-ship-with-their-code-en.md)). +- **Acceptance criteria are tested.** A test that covers a criterion of §11 quotes its + identifier (`CA-NN`); the mapping lives in [`docs/ca-matrix-fr.md`](docs/ca-matrix-fr.md). +- **A claim about the browser is measured.** What a platform's page or the browser does is + checked in a real Chromium, not recalled. A bug fix is verified by removing it: its test must + fail without it. +- **No prettier.** The code is formatted by hand; never run `prettier --write` + ([DEC0003](docs/idr/DEC0003-an-inert-prettier-configuration-en.md)). +- **Invisible characters are written as escapes** (`\uXXXX`) in sources and tests. +- **User-facing changes go to the changelog** and to the release notes, in English and French. + +Run `npm test`, `npm run build` and `npm run checks` before pushing. + +## Reviews + +Reviews of this repository are written in Conventional Comments, with the labels the toolkit +ships. See [labels and decorations](docs/guide/labels-en.md). + +## Documentation + +User documentation lives in [`docs/guide/`](docs/README-en.md), one page per subject, each in +English and French. A change to what the extension does or shows updates the page that +describes it, in both languages. The images are regenerated with `npm run docs:screenshots`. diff --git a/README-fr.md b/README-fr.md new file mode 100644 index 00000000..10569523 --- /dev/null +++ b/README-fr.md @@ -0,0 +1,198 @@ +# Conventional Comments Toolkit + +**Langues :** [English](README.md) | Français (ce fichier) + +[![CI](https://github.com/Reefact/conventional-comments-toolkit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Reefact/conventional-comments-toolkit/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/Reefact/conventional-comments-toolkit?include_prereleases)](https://github.com/Reefact/conventional-comments-toolkit/releases) +[![Licence : Apache-2.0](https://img.shields.io/badge/Licence-Apache--2.0-blue)](LICENSE) + +**Une extension de navigateur qui aide une équipe à écrire des +[Conventional Comments](https://conventionalcomments.org/) en revue de code, sur GitHub, +Azure DevOps et GitLab.** + +## Le problème + +Un commentaire de revue dit rarement ce qu'il est. + +```text +Cette boucle ne s'arrête jamais sur une réponse 4xx. +``` + +Est-ce un défaut à corriger avant de fusionner, une remarque en passant, une question ? +L'auteur doit deviner, et devine du même coup l'humeur du relecteur. Conventional Comments +tranche avec un préfixe : + +```text +issue (blocking): la boucle de reprise ne s'arrête jamais sur une réponse 4xx +``` + +Tout le monde trouve l'idée bonne. Puis tout le monde oublie de taper le préfixe, le tape +mal, ou l'emploie à sa façon. + +## La solution + +L'extension ajoute au champ de commentaire de la plateforme ce qui manque à la convention : +les labels à un clic, une réponse pendant la frappe, et un résultat lisible une fois publié. + +![La barre d'outils au-dessus d'un champ de commentaire : boutons de label, sélecteur de décoration et pastille Conforme](docs/images/toolbar-fr.png) + +Une erreur est nommée, avec sa correction à un clic : + +![Un commentaire dont le label est mal orthographié : le message E-UNKNOWN-LABEL et son bouton Corriger](docs/images/diagnostic-fr.png) + +Les commentaires publiés montrent leur label en badge, et leur sujet en titre : + +![Trois commentaires publiés dont le préfixe est rendu en badges](docs/images/badges-fr.png) + +*Les composants de l'extension, rendus par le code livré sur une page de test aux couleurs du +thème clair de GitHub. Ce ne sont pas des captures de github.com.* + +## Ce que vous obtenez + +- **Une barre d'outils** dans chaque champ de commentaire de revue : un bouton par label, un + sélecteur pour `(blocking)`, `(non-blocking)` et `(if-minor)`. +- **La saisie au clavier** : une liste de complétion (`/` ou `:`), des abréviations (`?ib` + + `Tab` donne `issue (blocking): `) et des raccourcis directs (`Alt+I`). +- **La validation pendant la frappe** : une pastille d'état, un message par problème, des + corrections en un clic. +- **Des badges** sur les commentaires publiés, un **bandeau** qui compte les fils bloquants + non résolus de la pull request, et un **filtre** des fils par label. +- **Des labels pour répondre**, ce que Conventional Comments ne couvre pas : `done`, `ack`, + `disagree`, `thanks`, plus `summary` et `reviewed` pour dire où en est une revue. Ce sont + des ajouts de cette boîte à outils, activés par défaut, qu'un dépôt peut désactiver. +- **Des règles par dépôt**, dans un seul fichier JSON, et au besoin par organisation. +- **Un blocage de l'envoi facultatif** (mode `enforce`), qui arrête un commentaire non + conforme avant sa publication. +- Une interface **en français et en anglais**. + +## Installer + +1. Téléchargez l'archive de votre navigateur depuis la + [page des releases](https://github.com/reefact/conventional-comments-toolkit/releases), + décompressez-la, puis chargez le dossier (`chrome://extensions` → Mode développeur → + Charger l'extension non empaquetée). +2. Dans la page de réglages qui s'ouvre, autorisez votre plateforme : l'extension reste + inactive partout tant qu'aucun domaine n'est autorisé. +3. Ouvrez une pull request et cliquez dans un nouveau commentaire. + +**→ [Prise en main](docs/guide/getting-started-fr.md)** détaille ces trois étapes en dix +minutes. + +## Plateformes + +| | GitHub | Azure DevOps | GitLab | +|---|:---:|:---:|:---:| +| Barre d'outils, saisie au clavier, validation | Oui | Oui | Oui (éditeur Markdown) | +| Badges, bandeau, filtre des fils | Oui | Oui | Oui | +| Configuration du dépôt, blocage de l'envoi | Oui | Oui | Pas encore | + +GitHub.com, Enterprise Cloud et Enterprise Server ; Azure DevOps Services et Server ; +gitlab.com. Chrome, Edge et les autres navigateurs Chromium, Firefox 128 ou supérieur. +[Ce qui fonctionne où, en détail](docs/guide/platforms-fr.md). + +## Configurer un dépôt + +L'extension n'a besoin d'aucune configuration. Un dépôt qui veut ses propres règles ajoute un +fichier `.conventional-comments.json` à la racine de sa branche par défaut : + +```json +{ + "version": 1, + "mode": "assist", + "labels": [ + { "id": "issue", "aliases": ["bug"] }, + { "id": "typo", "enabled": false } + ], + "toolCommands": ["/*", "@dependabot"] +} +``` + +[Chaque clé, avec des exemples](docs/guide/configuration-fr.md). + +## Ce qu'elle est, et ce qu'elle n'est pas + +**Elle assiste par défaut et ne bloque jamais.** En mode `assist`, un commentaire non +conforme est signalé et part quand même. Une équipe qui veut davantage passe un dépôt en +`enforce`, où le bouton d'envoi refuse un commentaire en erreur. + +**C'est un garde-fou, pas un mur.** L'extension agit dans le navigateur où elle est +installée. Un commentaire publié par l'API de la plateforme, un autre navigateur ou un poste +sans l'extension n'est pas contrôlé. + +**Elle ne contrôle pas la fusion.** Les fils bloquants non résolus sont signalés, jamais +empêchés de fusionner +([DEC0010](docs/idr/DEC0010-the-extension-is-the-whole-product-fr.md)). Une équipe qui veut +conditionner la fusion à la résolution des conversations s'appuie sur les réglages de sa +plateforme. + +**Elle contrôle la forme, jamais le fond.** Qu'une remarque soit juste, utile ou aimable +n'est pas son affaire. + +## Confidentialité + +Aucun contenu de commentaire, de code ou de diff ne quitte votre navigateur. Aucun jeton +n'est stocké. Aucun accès à un site n'est demandé à l'installation : vous l'accordez domaine +par domaine. La télémétrie est désactivée par défaut, et un dépôt ne peut pas l'activer. +[Politique de confidentialité](PRIVACY.md). + +## Documentation + +**→ [Commencez par le guide de dix minutes](docs/guide/getting-started-fr.md)** + +| | | +|---|---| +| [Index de la documentation](docs/README-fr.md) | Tout, organisé, en français et en anglais | +| [Rédiger des commentaires de revue](docs/guide/writing-comments-fr.md) | Le format, la barre d'outils, la pastille, les badges et le bandeau | +| [Saisie au clavier](docs/guide/keyboard-input-fr.md) | Complétion, abréviations, raccourcis directs | +| [Labels et décorations](docs/guide/labels-fr.md) | Chaque label, quand l'employer, ce qui rend un commentaire bloquant | +| [Diagnostics](docs/guide/diagnostics-fr.md) | Chaque code de la pastille, et comment le corriger | +| [Configuration](docs/guide/configuration-fr.md) | Le fichier du dépôt, clé par clé | +| [Modes et adoption](docs/guide/modes-and-adoption-fr.md) | `off`, `assist`, `enforce`, et comment y arriver | +| [Déployer pour une organisation](docs/guide/organization-fr.md) | Configuration partagée, plancher, hôtes, télémétrie | +| [FAQ et dépannage](docs/guide/faq-fr.md) | Quand quelque chose ne s'affiche pas | + +## Les labels que la boîte à outils ajoute + +Conventional Comments donne un vocabulaire à la **remarque** de revue et ne dit rien de la +**réponse** à une remarque. La boîte à outils livre ses propres labels pour cela. Ils **ne +font pas partie de Conventional Comments** ; un dépôt qui veut s'en tenir à la liste d'origine +les désactive. + +| Label | Signification | Aussi accepté | +|---|---|---| +| `thanks` | Remercie, sans prendre position sur le point ni sur le code. | `thx` | +| `done` | Le code a changé à la suite de la remarque. | `fixed` | +| `ack` | Reçu et accepté ; le code n'a pas changé. | `acknowledged` | +| `disagree` | Refuse la remarque, et le sujet dit pourquoi. Ne résout rien. | | +| `summary` | Fait le point sur la revue ou sur une passe : ce qui a été vérifié, ce qui reste ouvert. | | +| `reviewed` | Clôt votre revue : vos points sont traités. N'approuve rien. | | +| `decision` | Acte, avec son motif, qu'un point ne sera pas traité. | | + +[Quand employer chacun, et comment les désactiver](docs/guide/labels-fr.md#les-labels-qui-ne-font-pas-partie-de-conventional-comments). + +## Pour les agents IA + +Deux skills permettent à un agent IA de relire une pull request, ou de répondre à sa revue, +avec ce vocabulaire : [`skills/review-pull-request`](skills/review-pull-request/SKILL.md) et +[`skills/respond-to-review`](skills/respond-to-review/SKILL.md). Aucun des deux n'approuve ni +ne fusionne. [Skills de revue pour les agents IA](docs/guide/review-skills-fr.md). + +## Contribuer + +Les issues et les pull requests sont les bienvenues. Commencez par +[`CONTRIBUTING.md`](CONTRIBUTING.md) (en anglais). + +``` +npm install +npm test +npm run build +``` + +L'organisation du dépôt, ses commandes, son intégration continue et son état d'avancement +sont décrits dans [`docs/development-en.md`](docs/development-en.md) (en anglais). La +spécification normative est [`specifications-fr.md`](specifications-fr.md) ; les décisions +importantes sont consignées dans [`docs/idr/`](docs/idr/README-fr.md). + +## Licence + +[Apache-2.0](LICENSE). diff --git a/README.md b/README.md index 040dcc8a..4aad0cd1 100644 --- a/README.md +++ b/README.md @@ -1,290 +1,190 @@ -# conventional-comments-toolkit +# Conventional Comments Toolkit -Browser extension enforcing [Conventional Comments](https://conventionalcomments.org/) in code reviews, for GitHub (github.com, Enterprise Cloud/EMU, Enterprise Server) and Azure DevOps (Services, Server). +**Languages:** English (this file) | [Français](README-fr.md) -GitLab (gitlab.com) gets the authoring assistance and real-time validation, but not the send guard: the extension cannot read a repository's configuration there yet, so it never blocks on GitLab (specification, annex C). GitLab Self-Managed and Dedicated are not measured yet. +[![CI](https://github.com/Reefact/conventional-comments-toolkit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Reefact/conventional-comments-toolkit/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/Reefact/conventional-comments-toolkit?include_prereleases)](https://github.com/Reefact/conventional-comments-toolkit/releases) +[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue)](LICENSE) -The product is the browser extension, and only the extension (§2): authoring assistance and -real-time validation while writing review comments, an optional send guard (`enforce`, §5.4), -and a banner counting the pull request's unresolved blocking threads (§5.5). Convenience and -prevention; bypassable by construction. +**A browser extension that helps a team write [Conventional Comments](https://conventionalcomments.org/) +in code reviews, on GitHub, Azure DevOps and GitLab.** -**The toolkit does not control pull request completion** ([DEC0010](docs/idr/DEC0010-the-extension-is-the-whole-product-en.md)). -Unresolved blocking threads are *reported*, never prevented from merging. An earlier version of -the specification described a second component, a verifier running in the platform's CI and -publishing a required status check; it is removed, together with what existed only for it — -the resolution governance, the per-PR exemption, the activation date and the configuration -fingerprint. A team that wants merges gated on resolved conversations uses its platform's own -settings, such as required conversation resolution. +## The problem -No comment, code, or diff content ever leaves the browser. The full specification (the normative source) is [`specifications-fr.md`](./specifications-fr.md) (in French). +A review comment rarely says what it is. -## Layout +```text +This loop never stops on a 4xx answer. +``` -A TypeScript monorepo (npm workspaces). The full breakdown is in [`docs/architecture-fr.md`](./docs/architecture-fr.md). +Is this a defect to fix before merging, a remark in passing, a question? The author has to +guess, and guesses the reviewer's mood along with it. Conventional Comments settles it with a +prefix: -``` -packages/core @cct/core parser, validator, config — every validation rule -packages/adapters/* @cct/adapter-* platform adapters + shared editor plumbing -packages/extension @cct/extension Manifest V3 extension — toolbar, quick input, feedback, guard -spikes/p1-prime P1' spike programmatic-write assumption, validated in Chromium -skills/* agent skills review a pull request, or answer its review, in Conventional Comments +```text +issue (blocking): the retry loop never stops on a 4xx answer ``` -`packages/core/` holds every validation rule and has no dependency on the browser or on any -platform; the adapters and the extension consume it. See -[`docs/architecture-fr.md`](./docs/architecture-fr.md). +Everyone agrees it is a good idea. Then everyone forgets to type the prefix, mistypes it, or +uses it their own way. -## Getting started +## The solution -``` -npm install -npm test # unit + integration tests (mapped to the acceptance criteria) -npm run build # TypeScript build of every package -npm run checks # repository guards: CA matrix ↔ tests, invisible-character escapes -npm run spike # P1' spike: programmatic-write assumption in Chromium (§9.3) -npm run build:extension # MV3 bundle into packages/extension/dist-ext (+ Firefox variant) +The extension adds what the convention lacks to the platform's own comment field: the labels +one click away, an answer as you type, and a readable result once published. + +![The toolbar above a comment field: label buttons, the decoration selector and the Compliant pill](docs/images/toolbar-en.png) + +A mistake is named, with its correction one click away: + +![A comment with a misspelt label: the E-UNKNOWN-LABEL message and its Fix button](docs/images/diagnostic-en.png) + +Published comments show their label as a badge, and their subject as a title: + +![Three published comments whose prefix is shown as badges](docs/images/badges-en.png) + +*The extension's own components, rendered from the shipped code on a test page in the colours +of GitHub's light theme. Not screenshots of github.com.* + +## What you get + +- **A toolbar** in every review comment field: one button per label, a selector for + `(blocking)`, `(non-blocking)` and `(if-minor)`. +- **Keyboard input**: a completion list (`/` or `:`), abbreviations (`?ib` + `Tab` gives + `issue (blocking): `) and direct shortcuts (`Alt+I`). +- **Validation as you type**: a status pill, a message per problem, one-click fixes. +- **Badges** on published comments, a **banner** counting the pull request's unresolved + blocking threads, and a **filter** of threads by label. +- **Labels for replying**, which Conventional Comments does not cover: `done`, `ack`, + `disagree`, `thanks`, plus `summary` and `reviewed` to say where a review stands. They are + additions of this toolkit, enabled by default, that a repository can disable. +- **Rules per repository**, in one JSON file, and optionally per organisation. +- **An optional send guard** (`enforce` mode) that stops a non-compliant comment before it is + published. +- **English and French** interface. + +## Install + +1. Download the archive for your browser from the + [releases page](https://github.com/reefact/conventional-comments-toolkit/releases), unzip + it, and load the folder (`chrome://extensions` → Developer mode → Load unpacked). +2. In the settings page that opens, allow your platform: the extension is inactive everywhere + until you allow a domain. +3. Open a pull request and click into a new comment. + +**→ [Getting started](docs/guide/getting-started-en.md)** walks through these three steps in +ten minutes. + +## Platforms + +| | GitHub | Azure DevOps | GitLab | +|---|:---:|:---:|:---:| +| Toolbar, keyboard input, validation | Yes | Yes | Yes (Markdown editor) | +| Badges, banner, thread filter | Yes | Yes | Yes | +| Repository configuration, send guard | Yes | Yes | Not yet | + +GitHub.com, Enterprise Cloud and Enterprise Server; Azure DevOps Services and Server; +gitlab.com. Chrome, Edge and other Chromium browsers, Firefox 128 or later. +[What works where, in detail](docs/guide/platforms-en.md). + +## Configure a repository + +The extension needs no configuration. A repository that wants its own rules adds a +`.conventional-comments.json` file at the root of its default branch: + +```json +{ + "version": 1, + "mode": "assist", + "labels": [ + { "id": "issue", "aliases": ["bug"] }, + { "id": "typo", "enabled": false } + ], + "toolCommands": ["/*", "@dependabot"] +} ``` -Starting from a machine with none of this installed? See the step-by-step Windows/PowerShell -guide: [`docs/extension-setup-en.md`](./docs/extension-setup-en.md) (French: -[`docs/extension-setup-fr.md`](./docs/extension-setup-fr.md)). - -**Can't run `npm` at all?** Every tagged release carries the extension as a ready-to-load -zip — one for Chromium, one for Firefox. Download it from the -[releases page](https://github.com/reefact/conventional-comments-toolkit/releases), -unzip it, and load the folder (`chrome://extensions` → Developer mode → Load unpacked). -No Node, no npm, no Git. That path is for **trying the extension** and for machines where -the build chain can't be installed — it is not a deployment channel: an extension loaded -from a zip never auto-updates, and §10 routes every delivery of the extension through the -public stores. How a release is cut: [`docs/release-fr.md`](./docs/release-fr.md). - -## Configuration - -A repository is configured by a `.conventional-comments.json` file on its default branch — -see [`.conventional-comments.example.json`](./.conventional-comments.example.json) for the -shape of every key (it is **not** the product defaults, which live in -`packages/core/src/config/defaults.ts`). Resolution, floor bounds, merge semantics and -when a change takes effect are specified in §8 and implemented in `packages/core/src/config/`. - -**Upgrading from a version without `toolCommands`.** Slash commands used to be exempted -through a list built into the GitHub adapter (`/azp`, `/rebase`). That list is gone, and -`toolCommands` is **empty by default**, so those commands now need a label like any other -comment until the repository declares them — in `enforce` mode a `/rebase` is rejected -where it previously passed. A repository that relied on the built-in exemption restores it, -and widens it to every slash command, by adding `"/*"` to `toolCommands`. The example file -above carries the full recommended GitHub list, mentions included. - -Note that this behaviour lives in `core/`, not in the configuration: two extensions running -different `core/` versions apply different rules to the same file. The lever for requiring a -`core/` version across an organization is `coreMinVersion` (§8.1.3, rule 5). - -**Retired keys.** `formatSeverity`, `overrideLabel`, `resolverOverrideGroup`, `activation` and -`docUrl` served only the removed verifier and have left the schema (§8.2). A configuration that -still carries them stays readable: each is an unknown key, ignored and reported as a -configuration warning, with no fallback. `"mode": "warn"` is read as `"assist"`, with an -"obsolete value" warning (§7). Remove them to clear the warnings. - -### Response labels, `summary` and `reviewed` (on by default, not part of Conventional Comments) - -Conventional Comments gives review **feedback** a vocabulary and says nothing about **replying** -to it. The toolkit adds four response labels of its own, plus `summary` to recap a review pass -and `reviewed` to close your review. These six **added labels** are **not part of Conventional -Comments**: an extension of this tool, shipped enabled, that a repository can turn off (§3.1, §3.2). Every label the toolkit ships is -enabled by default, including Conventional Comments' `typo` and `polish`; disable the ones you -don't want. The one exception is `quibble`, shipped but disabled: Conventional Comments itself -defines it as a `nitpick` under another name. Enable it with `{ "id": "quibble", "enabled": true }`. +[Every key, with examples](docs/guide/configuration-en.md). + +## What it is, and what it is not + +**It assists by default and never blocks.** In `assist` mode, a non-compliant comment is +flagged and still goes out. A team that wants more switches a repository to `enforce`, where +the send button refuses a comment with an error. + +**It is a guard rail, not a wall.** The extension acts in the browser where it is installed. +A comment posted through the platform's API, another browser or a machine without the +extension is not checked. + +**It does not control the merge.** Unresolved blocking threads are reported, never prevented +from merging ([DEC0010](docs/idr/DEC0010-the-extension-is-the-whole-product-en.md)). A team +that wants merges gated on resolved conversations uses its platform's own settings. + +**It checks the form, never the content.** Whether a remark is right, useful or kind is not +its business. + +## Privacy + +No comment, code or diff content ever leaves your browser. No token is stored. No site access +is requested at installation: you grant it one domain at a time. Telemetry is off by default +and cannot be turned on by a repository. [Privacy policy](PRIVACY.md). + +## Documentation + +**→ [Start with the ten-minute guide](docs/guide/getting-started-en.md)** + +| | | +|---|---| +| [Documentation index](docs/README-en.md) | Everything, organised, in English and French | +| [Writing review comments](docs/guide/writing-comments-en.md) | The format, the toolbar, the pill, badges and the banner | +| [Keyboard input](docs/guide/keyboard-input-en.md) | Completion, abbreviations, direct shortcuts | +| [Labels and decorations](docs/guide/labels-en.md) | Every label, when to use it, what makes a comment blocking | +| [Diagnostics](docs/guide/diagnostics-en.md) | Every code of the pill, and how to fix it | +| [Configuration](docs/guide/configuration-en.md) | The repository file, key by key | +| [Modes and adoption](docs/guide/modes-and-adoption-en.md) | `off`, `assist`, `enforce`, and how to get there | +| [Deploying for an organisation](docs/guide/organization-en.md) | Shared configuration, floor, hosts, telemetry | +| [FAQ and troubleshooting](docs/guide/faq-en.md) | When something does not show up | + +## Labels the toolkit adds + +Conventional Comments gives review **feedback** a vocabulary and says nothing about +**replying** to it. The toolkit ships labels of its own for that. They are **not part of +Conventional Comments**; a repository that wants the upstream list only disables them. | Label | Meaning | Also accepted | |---|---|---| | `thanks` | Says thank you, taking no position on the point or the code. | `thx` | | `done` | The code changed because of the remark. | `fixed` | | `ack` | Received and accepted; the code has not changed. | `acknowledged` | -| `disagree` | Declines the remark, and the subject says why. Carries no authority, resolves nothing. | | -| `summary` | Recaps the review or one pass: what was checked, what is still open. Raises no point, answers none, closes nothing. | | -| `reviewed` | Closes your own review: your points are dealt with, you have nothing to add. Approves nothing. | | +| `disagree` | Declines the remark, and the subject says why. Resolves nothing. | | +| `summary` | Recaps the review or one pass: what was checked, what is still open. | | +| `reviewed` | Closes your own review: your points are dealt with. Approves nothing. | | +| `decision` | Records, with a reason, that a point will not be addressed. | | -```text -issue (blocking): platform CSS tokens leak into the shared stylesheet -done: removed the platform-specific token -``` - -`reviewed` is the label people used to fake with `praise: review done`. It says your review is -over; approval stays with the platform's own control. It is not a reply: it answers no point, -it says where your review stands. `thanks` fills the gap a plain "thanks!" reply left: with -`scope.validateReplies` on, it had to be written `note: thanks`. - -`summary` is the recap of a review pass — what was checked, what is still open — that used to be -written as plain prose or under `note:`. It is the counterpart of `reviewed`: `summary` says where -an ongoing review stands, `reviewed` that it is closed. A `summary` never stands in for -`reviewed`, even when no point is left open; posted after your `reviewed`, it reads as if your -review had reopened. - -**When to post `reviewed`.** It closes your review as a whole, not one reading pass: a review -covers raising points, following how they are handled and checking the fixes. Post it once each -of your points is dealt with — fixed and checked, or set aside by a reply you accept, which a -non-blocking point may legitimately be — and a last read turns up nothing new. While one of your -points is still open, whatever its priority, so is your review. It only covers the pull request -as you examined it: any later change reopens your review, the new changes must be examined, and -a new `reviewed` may only be posted once every closing condition holds again. Each reviewer -closes their own. What the pull request needs to be merged — approvals, required reviewers — -stays with the platform: the toolkit does not count `reviewed`, and no number of them amounts to -an approval. This is a convention the toolkit states, not one it checks (§3.2). - -**Describe a label: `labels[].description` and `labels[].usage`.** A label's two tooltips answer -two questions. The **badge** of a published comment tells whoever reads it what the comment -means; the **toolbar button** tells whoever writes when to use the label, followed by an example. -A repository or an organisation can write its own texts, for a label it creates or for a shipped -one: +[When to use each, and how to disable them](docs/guide/labels-en.md#labels-that-are-not-part-of-conventional-comments). -```json -{ "labels": [ { "id": "risk", - "description": "A regression risk raised by the reviewer.", - "usage": "Flag a regression risk to assess before merging." }, - { "id": "issue", "description": "Here: a defect that breaks a test or a contract." } ] } -``` +## For AI agents -`description` goes to the badge, `usage` to the button; without `usage`, the button shows -`description`. Written, each replaces the shipped text (and, on the button, its example); written -empty (`""`), it removes that tooltip; left out, a shipped label keeps its texts. They are shown -as written, whatever the interface language, and change no verdict. - -Every label has a **kind** (`labels[].kind`): `"remark"` raises a point, `"reply"` answers one, -and `"status"` does neither — it says where the review stands (`summary`, `reviewed`). The -toolbar shows the remark labels first, then the status labels, which always close that line; -then, always on a line of their own under a thin horizontal rule, the reply labels: `thanks`, -`done`, `ack`, `decision`, `disagree`. A thin double rule then separates the labels from the -decorations. A label you declare is `"remark"` unless you write `"kind": "status"` or -`"kind": "reply"`. The kind changes no verdict; it keeps replies and status labels out of the -label statistics that measure review culture, such as the share of `praise`. - -**Button order.** By default, the order of conventionalcomments.org, then `summary` and -`reviewed`; the replies go from the warmest to the firmest. A remark label you create comes -before `summary` and `reviewed`, which close the first line. In the extension's options, *Button order* takes a -comma-separated list, for example `suggestion,nitpick,disagree`: the labels you list come first -in their own group — remarks, status labels or replies —, the others follow in the default order. Spaces are ignored. It is a personal -preference, synced by your browser; it changes no verdict and applies to the next comment box -that opens. The completion list (`/` or `:`) follows the same order. - -**To stick to Conventional Comments**, disable them, one entry each — there is no separate -switch (§8.2). The extension's options page shows this block and copies it for you: +Two skills let an AI agent review a pull request, or answer its review, with this vocabulary: +[`skills/review-pull-request`](skills/review-pull-request/SKILL.md) and +[`skills/respond-to-review`](skills/respond-to-review/SKILL.md). Neither approves nor merges. +[Review skills for AI agents](docs/guide/review-skills-en.md). -```json -{ "labels": [ { "id": "thanks", "enabled": false }, - { "id": "done", "enabled": false }, - { "id": "ack", "enabled": false }, - { "id": "disagree", "enabled": false }, - { "id": "summary", "enabled": false }, - { "id": "reviewed", "enabled": false } ] } -``` +## Contributing -With no existing `.conventional-comments.json`, this block can be the whole file. Otherwise, add -the six entries to its existing `labels` array, or create that property, without replacing the -other keys: pasting the block into an existing file makes it invalid JSON, and replacing the file -drops your other settings. +Issues and pull requests are welcome. Start with [`CONTRIBUTING.md`](CONTRIBUTING.md). -The labels change **which labels exist**, nothing else. They do not require replies to carry a -label: that is `scope.validateReplies`, still `false` by default, so a reply is not validated at -all unless you turn it on (§4.1). They do not change the mode, and none of the six can make a -thread blocking. `decision` is unchanged: it is the reply with which those who carry the pull -request — its author, its maintainers — record, with a reason, that a point will not be addressed -(§6.1.1). `disagree` is an opinion. Neither resolves a thread. +``` +npm install +npm test +npm run build +``` -**Upgrading with a label already called `thanks`, `done`, `ack`, `disagree`, `summary` or `reviewed`.** Your entry -now merges into the shipped one (§8.1.4) and inherits `alwaysNonBlocking: true`, so -`done (blocking):` becomes `E-CONFLICT`. Restore your label with: +The layout of the repository, its commands, its continuous integration and its status against +the specification are in [`docs/development-en.md`](docs/development-en.md). The normative +specification is [`specifications-fr.md`](specifications-fr.md) (in French); the important +decisions are recorded in [`docs/idr/`](docs/idr/README-en.md). -```json -{ "labels": [ { "id": "done", "alwaysNonBlocking": false } ] } -``` +## License -A label of your own called `fixed`, `acknowledged` or `thx` is a different case. Two active labels may -not share a name: an alias that repeats another active label's id is removed from its carrier. -Since `done` is enabled by default, it is the shipped alias `fixed` that goes and your label -that stays. An alias carried by two labels is removed from both. Each removal is reported as a -configuration warning (§8.2). - -## Review skills for AI agents - -Two skills let an AI agent take part in a review the way this toolkit expects. Each is a -directory under `skills/`, whose `SKILL.md` Claude Code loads as is and any other agent can be -given as instructions. Install or hand over **the whole directory**, not the `SKILL.md` alone: the -reviewer's relies on the files beside it — how to choose session identifiers, and the Slugger -theme it draws them from. - -- [`skills/review-pull-request`](./skills/review-pull-request/SKILL.md), for the **reviewer**: - publishes findings as Conventional Comments, rated P0 to P3, follows them up until each fix is - verified, and closes its review with `reviewed:` once nothing is left. It never approves and - never merges: those stay human decisions. -- [`skills/respond-to-review`](./skills/respond-to-review/SKILL.md), for the **author** of the - pull request: answers every finding and question with `done:`, `ack:`, `disagree:` or - `thanks:` — or `note:` to inform and `question:` to ask back —, pushes the fixes, and never - posts `reviewed` or `decision`. - -Both read the repository's `.conventional-comments.json` first, so they only use the labels it -enables. The reviewer ends each of its comments with a `[session:]` line, the same for -the whole review session, and the author copies it into the reply to that comment, so a reader can -tell parallel review sessions apart. Each agent session draws its own identifier from a random -source, checks that the pull request does not carry it yet, and never takes one from the pull -request, from another session or from an earlier conversation. The identifier is a readable name drawn by -[Slugger](https://github.com/Reefact/slugger), used without asking when it already runs — or, on -Linux x64 without .NET, through its native build, downloaded and checked against a pinned SHA-256. -The choice is made once per installation and recorded in a committed `session-id.md` beside the -skill: where none is recorded yet, the reviewer skill offers Slugger once and records the answer — -Slugger, or a GUID. Once a choice is recorded it is never asked again; where a recorded Slugger -cannot run on a machine, that session draws a GUID by a command instead, and its report says why. -A Slugger name also gets a description: one idiomatic sentence that renders its words, in the -language of the review's comments, appended after an em dash and in italics — -`[session:disheartening-reviewed-implementation — *We reviewed the implementation, and frankly, -it was disheartening.*]`. The extension shows the name, and the -sentence on hover; the author's reply copies the marker as written, description included. - -## Modes and adoption (§7) - -`off`, `assist` (default), `enforce`; the recommended path is `assist` → `enforce` on a pilot -repository → rollout. `warn` is retired and read as `assist`. Operational procedures — the -prerequisite for `enforce` and the rollback order — are in -[`docs/operations-fr.md`](./docs/operations-fr.md). - -## Acceptance criteria - -Every acceptance criterion of §11 is covered by at least one automated test. -The mapping from each criterion to its test files is in -[`docs/ca-matrix-fr.md`](./docs/ca-matrix-fr.md); the `CA-NN` identifiers appear literally in the -tests, and CI fails if that stops being true. - -## Continuous integration - -Five workflows, each answering a different question. Only **CI** is meant to be a required -check on `main`; the others report without gating. - -| Workflow | Question it answers | When | -|----------|--------------------|------| -| [`ci.yml`](./.github/workflows/ci.yml) | Does everything compile and does every test pass, on both supported Node versions? | push to `main`, every PR | -| [`conformance.yml`](./.github/workflows/conformance.yml) | Do the repository's own rules still hold — CA matrix in step with the tests, invisible characters written as escapes, normative spec untouched by a code PR? | push to `main`, every PR | -| [`extension-package.yml`](./.github/workflows/extension-package.yml) | Does the MV3 bundle build, stay free of remote code (§10), and keep both manifests loadable? Publishes the Chromium and Firefox bundles as artifacts. | push to `main`, PRs touching `packages/` | -| [`browser-smoke.yml`](./.github/workflows/browser-smoke.yml) | Does the §9.3 programmatic-write strategy still hold in a current Chromium — the one thing happy-dom cannot tell us? | daily (04:17 UTC), PRs touching adapters or the spike | -| [`release.yml`](./.github/workflows/release.yml) | Can someone install the extension without any build chain? Builds, verifies and publishes the Chromium and Firefox zips as a GitHub Release. | tag `v*`, manual dry run | - -The selector smoke test of §9.4 runs on pages captured from each platform -(`packages/adapters//test/fixtures/pages/`): `npm run check:captured-selectors` checks that -happy-dom, where the real-page tests run, matches exactly the elements Chromium matches. -Against the *live* platforms, only what an anonymous visitor can see is checked, weekly, by -[`github-selectors-canary.yml`](./.github/workflows/github-selectors-canary.yml). Composers -need a signed-in session and are not checked live. - -## Status against the specification phases (§14) - -| Phase | Content | State | -|-------|---------|-------| -| P1 | `core/` (parser, validator, config) + unit tests | Implemented | -| P1' | Programmatic-write spike (GitHub React + Azure DevOps) | Assumption validated in Chromium; remaining platform assumptions documented with their fallbacks (`spikes/p1-prime/README-fr.md`) | -| P2 | Extension `assist` on GitHub | Implemented | -| P3 | Azure DevOps adapter | Implemented, with the P1' fallbacks in place | -| P4 | Opt-in telemetry and the §12 indicators | **Partly implemented.** Opt-in counters ship: a label inserted through the extension, a diagnostic code shown, a selector degradation — with mode and repository, never free text —, sent only to a collection point declared by enterprise policy and accepted by the person. **The §12 indicators do not follow from them yet**: no event counts written or submitted comments, so the compliance and warning *rates* have no denominator, and a label typed or pasted by hand is missing from the distribution. Those events and the restitution remain to be built | -| P6 | `enforce` (send guard, §5.4) on a pilot repo, then rollout | **Blocked on P4** (§14). The send guard is implemented, and choosing the pilot and writing the rollback procedure can start now; switching the pilot to `enforce` waits for the §12 indicators. Rollback order: [`docs/operations-fr.md`](./docs/operations-fr.md) | - -P5 (the verifier) and P0 (the baseline measurement, which only served an indicator that needed -the platform's API) are removed from the specification; their identifiers are not reused. - -License: Apache-2.0. +[Apache-2.0](LICENSE). diff --git a/docs/README-en.md b/docs/README-en.md new file mode 100644 index 00000000..6b9b4d91 --- /dev/null +++ b/docs/README-en.md @@ -0,0 +1,77 @@ +# Conventional Comments Toolkit — documentation + +**Languages:** English (this file) | [Français](README-fr.md) + +The toolkit is a browser extension that helps a team write +[Conventional Comments](https://conventionalcomments.org/) in code reviews: a toolbar and a +validation while you write, badges and a banner once comments are published. It assists by +default and blocks only where a team asks it to. + +## Start here + +**New to the extension?** → [**Getting started**](guide/getting-started-en.md): ten minutes +from nothing installed to a first comment written with the toolbar. + +## Using the extension + +Read them in order the first time. + +| Guide | What you get | +|---|---| +| [Getting started](guide/getting-started-en.md) | Install, allow your platform, write a first comment | +| [Writing review comments](guide/writing-comments-en.md) | The format, the toolbar, the status pill, what is validated, badges, banner and filter | +| [Keyboard input](guide/keyboard-input-en.md) | The completion list, abbreviations expanded by `Tab`, `Alt` shortcuts | +| [The settings page](guide/settings-en.md) | Allowed domains, personal preferences, the status journal and the diagnostic archive | +| [FAQ and troubleshooting](guide/faq-en.md) | Why something does not show up, what a message means, what the extension is not | + +## Reference + +Look-up material. + +| Page | Covers | +|---|---| +| [Labels and decorations](guide/labels-en.md) | Every shipped label and when to use it, the labels the toolkit adds, decorations, what makes a comment blocking | +| [Diagnostics](guide/diagnostics-en.md) | Every code the pill can show, with an example and its fix | +| [Configuration](guide/configuration-en.md) | The repository file key by key, how levels combine, recipes, upgrade notes | +| [Platforms](guide/platforms-en.md) | What works on GitHub, Azure DevOps and GitLab, which domain to allow, supported browsers | + +## For a team or an organisation + +| Guide | What you get | +|---|---| +| [Modes and adoption](guide/modes-and-adoption-en.md) | `off`, `assist`, `enforce`; what blocking does and does not do; the path to it and the way back | +| [Deploying for an organisation](guide/organization-en.md) | The enterprise policy: shared configuration, floor, hosts, telemetry, forced installation | +| [Review skills for AI agents](guide/review-skills-en.md) | Letting an agent review, or answer a review, with this vocabulary | +| [Privacy policy](../PRIVACY.md) | What is stored, what is sent, and what never leaves the browser | +| [Release notes](release-notes-1.x-en.md) | What changed, version by version, for people who use the extension | + +## How it all fits together + +```mermaid +flowchart TD + accTitle: How the documentation fits together + accDescr: Getting started leads to Writing review comments, which branches to Keyboard input, Labels and decorations, and Diagnostics. Labels and Diagnostics lead to Configuration, which leads to Modes and adoption, then to Deploying for an organisation. Getting started also leads to The settings page and Platforms, and The settings page to the FAQ. Labels and decorations also leads to Review skills for AI agents. + S["Getting started"] --> W["Writing review comments"] + S --> P["The settings page"] + S --> F["Platforms"] + W --> K["Keyboard input"] + W --> L["Labels and decorations"] + W --> D["Diagnostics"] + L --> C["Configuration"] + D --> C + C --> M["Modes and adoption"] + M --> O["Deploying for an organisation"] + L --> A["Review skills for AI agents"] + P --> Q["FAQ and troubleshooting"] + style S fill:#e8f5e9,stroke:#43a047,color:#1b5e20 +``` + +## Working on the toolkit + +| Document | Content | +|---|---| +| [Contributing](../CONTRIBUTING.md) | The rules of the repository, in short | +| [Development](development-en.md) | Layout, commands, continuous integration, status against the specification | +| [Specification](../specifications-fr.md) | The normative functional reference (in French) | +| [Important Decision Records](idr/README-en.md) | Why the repository is the way it is | +| [Changelog](../CHANGELOG.md) | Every notable change | diff --git a/docs/README-fr.md b/docs/README-fr.md new file mode 100644 index 00000000..aff8459c --- /dev/null +++ b/docs/README-fr.md @@ -0,0 +1,78 @@ +# Conventional Comments Toolkit — documentation + +**Langues :** [English](README-en.md) | Français (ce fichier) + +La boîte à outils est une extension de navigateur qui aide une équipe à écrire des +[Conventional Comments](https://conventionalcomments.org/) en revue de code : une barre +d'outils et une validation pendant la rédaction, des badges et un bandeau une fois les +commentaires publiés. Elle assiste par défaut et ne bloque que là où une équipe le demande. + +## Par où commencer + +**Vous découvrez l'extension ?** → [**Prise en main**](guide/getting-started-fr.md) : dix +minutes pour passer de rien d'installé à un premier commentaire écrit avec la barre d'outils. + +## Utiliser l'extension + +À lire dans l'ordre la première fois. + +| Guide | Ce que vous y trouvez | +|---|---| +| [Prise en main](guide/getting-started-fr.md) | Installer, autoriser votre plateforme, écrire un premier commentaire | +| [Rédiger des commentaires de revue](guide/writing-comments-fr.md) | Le format, la barre d'outils, la pastille, ce qui est validé, les badges, le bandeau et le filtre | +| [Saisie au clavier](guide/keyboard-input-fr.md) | La liste de complétion, les abréviations dépliées par `Tab`, les raccourcis `Alt` | +| [La page de réglages](guide/settings-fr.md) | Domaines autorisés, préférences personnelles, journal d'état et archive de diagnostic | +| [FAQ et dépannage](guide/faq-fr.md) | Pourquoi quelque chose ne s'affiche pas, ce que veut dire un message, ce que l'extension n'est pas | + +## Référence + +Des pages à consulter au besoin. + +| Page | Couvre | +|---|---| +| [Labels et décorations](guide/labels-fr.md) | Chaque label livré et quand l'employer, les labels que la boîte à outils ajoute, les décorations, ce qui rend un commentaire bloquant | +| [Diagnostics](guide/diagnostics-fr.md) | Chaque code que la pastille peut afficher, avec un exemple et sa correction | +| [Configuration](guide/configuration-fr.md) | Le fichier du dépôt clé par clé, la combinaison des niveaux, des recettes, les notes de migration | +| [Plateformes](guide/platforms-fr.md) | Ce qui fonctionne sur GitHub, Azure DevOps et GitLab, quel domaine autoriser, les navigateurs pris en charge | + +## Pour une équipe ou une organisation + +| Guide | Ce que vous y trouvez | +|---|---| +| [Modes et adoption](guide/modes-and-adoption-fr.md) | `off`, `assist`, `enforce` ; ce que le blocage fait et ne fait pas ; le chemin pour y arriver et le retour arrière | +| [Déployer pour une organisation](guide/organization-fr.md) | La politique d'entreprise : configuration partagée, plancher, hôtes, télémétrie, installation forcée | +| [Skills de revue pour les agents IA](guide/review-skills-fr.md) | Faire relire un agent, ou le faire répondre à une revue, avec ce vocabulaire | +| [Politique de confidentialité](../PRIVACY.md) | Ce qui est stocké, ce qui est envoyé, et ce qui ne quitte jamais le navigateur | +| [Notes de version](release-notes-1.x-fr.md) | Ce qui a changé, version par version, pour les personnes qui utilisent l'extension | + +## Comment tout cela s'articule + +```mermaid +flowchart TD + accTitle: Comment la documentation s'articule + accDescr: La prise en main mène à Rédiger des commentaires de revue, qui mène à la saisie au clavier, aux labels et décorations, et aux diagnostics. Labels et diagnostics mènent à la configuration, puis aux modes et à l'adoption, puis au déploiement pour une organisation. La prise en main mène aussi à la page de réglages et aux plateformes, et la page de réglages à la FAQ. Labels et décorations mène aussi aux skills de revue pour les agents IA. + S["Prise en main"] --> W["Rédiger des commentaires de revue"] + S --> P["La page de réglages"] + S --> F["Plateformes"] + W --> K["Saisie au clavier"] + W --> L["Labels et décorations"] + W --> D["Diagnostics"] + L --> C["Configuration"] + D --> C + C --> M["Modes et adoption"] + M --> O["Déployer pour une organisation"] + L --> A["Skills de revue pour les agents IA"] + P --> Q["FAQ et dépannage"] + style S fill:#e8f5e9,stroke:#43a047,color:#1b5e20 +``` + +## Travailler sur la boîte à outils + +| Document | Contenu | +|---|---| +| [Contribuer](../CONTRIBUTING.md) | Les règles du dépôt, en bref (en anglais) | +| [Développement](development-en.md) | Organisation, commandes, intégration continue, état d'avancement (en anglais) | +| [Spécification](../specifications-fr.md) | La référence fonctionnelle normative | +| [Registre des décisions](idr/README-fr.md) | Pourquoi le dépôt est ce qu'il est | +| [Changelog](../CHANGELOG.md) | Chaque changement notable (en anglais) | +| [Architecture](architecture-fr.md), [exploitation](operations-fr.md), [releases](release-fr.md) | Documents de l'équipe | diff --git a/docs/development-en.md b/docs/development-en.md new file mode 100644 index 00000000..6775a5a8 --- /dev/null +++ b/docs/development-en.md @@ -0,0 +1,117 @@ +# Development + +For people who work **on** the toolkit. To use the extension, start with the +[user guide](README-en.md). + +The working rules of the repository are in [`CLAUDE.md`](../CLAUDE.md) (in French; they hold +for humans and agents alike) and its important decisions in [`docs/idr/`](idr/README-en.md). +[`CONTRIBUTING.md`](../CONTRIBUTING.md) is the short version. + +## Layout + +A TypeScript monorepo (npm workspaces). The full breakdown is in +[`architecture-fr.md`](architecture-fr.md). + +``` +packages/core @cct/core parser, validator, config — every validation rule +packages/adapters/* @cct/adapter-* platform adapters + shared editor plumbing +packages/extension @cct/extension Manifest V3 extension — toolbar, quick input, feedback, guard +spikes/ browser measurements what happy-dom cannot tell, measured in a real Chromium +skills/* agent skills review a pull request, or answer its review, in Conventional Comments +``` + +`packages/core/` holds every validation rule and has no dependency on the browser or on any +platform; the adapters and the extension consume it. + +## Getting started + +``` +npm install +npm test # unit + integration tests (mapped to the acceptance criteria) +npm run build # TypeScript build of every package +npm run checks # repository guards that need no browser, build included +npm run build:extension # MV3 bundle into packages/extension/dist-ext (+ Firefox variant) +``` + +Starting from a machine with none of this installed? See the step-by-step Windows/PowerShell +guide: [`extension-setup-en.md`](extension-setup-en.md) (French: +[`extension-setup-fr.md`](extension-setup-fr.md)). + +Some commands question the **browser** rather than the code, and drive a real Chromium through +`playwright-core`: `npm run smoke:mv3`, `npm run spike`, and most `npm run check:*` commands +listed in [`CLAUDE.md`](../CLAUDE.md). Once per machine: `npx playwright-core install chromium`. +`package.json` is the reference for what exists. + +The images of the documentation are produced by `npm run docs:screenshots`, from the shipped +components ([`scripts/doc-screenshots.mjs`](../scripts/doc-screenshots.mjs)). Run it again +when the toolbar, the pill or the badges change. + +## The specification + +[`specifications-fr.md`](../specifications-fr.md) (in French) is the **normative** functional +reference. It is never edited to match the implementation; an amendment is a design decision, +and may ship with the code that implements it +([DEC0004](idr/DEC0004-spec-amendments-ship-with-their-code-en.md)). + +## Acceptance criteria + +Every acceptance criterion of §11 is covered by at least one automated test. The mapping from +each criterion to its test files is in [`ca-matrix-fr.md`](ca-matrix-fr.md); the `CA-NN` +identifiers appear literally in the tests, and CI fails if that stops being true. + +## Continuous integration + +Only **CI** is meant to be a required check on `main`; the others report without gating. +[`.github/workflows/`](../.github/workflows) is the reference. + +| Workflow | Question it answers | When | +|----------|--------------------|------| +| [`ci.yml`](../.github/workflows/ci.yml) | Does everything compile and does every test pass, on both supported Node versions? | push to `main`, every PR | +| [`conformance.yml`](../.github/workflows/conformance.yml) | Do the repository's own rules still hold — CA matrix in step with the tests, invisible characters written as escapes, normative spec untouched by a code PR? | push to `main`, every PR | +| [`extension-package.yml`](../.github/workflows/extension-package.yml) | Does the MV3 bundle build, stay free of remote code (§10), and keep both manifests loadable? Publishes the Chromium and Firefox bundles as artifacts. | push to `main`, PRs touching `packages/` | +| [`browser-smoke.yml`](../.github/workflows/browser-smoke.yml) | Does the §9.3 programmatic-write strategy still hold in a current Chromium — the one thing happy-dom cannot tell us? | daily (04:17 UTC), PRs touching adapters or the spike | +| [`release.yml`](../.github/workflows/release.yml) | Can someone install the extension without any build chain? Builds, verifies and publishes the Chromium and Firefox zips as a GitHub Release. | tag `v*`, manual dry run | + +The selector smoke test of §9.4 runs on pages captured from each platform +(`packages/adapters//test/fixtures/pages/`): `npm run check:captured-selectors` checks that +happy-dom, where the real-page tests run, matches exactly the elements Chromium matches. +Against the *live* platforms, only what an anonymous visitor can see is checked, weekly, by +[`github-selectors-canary.yml`](../.github/workflows/github-selectors-canary.yml). Composers +need a signed-in session and are not checked live. + +## Releasing + +How a release is cut: [`release-fr.md`](release-fr.md). The changelog is +[`CHANGELOG.md`](../CHANGELOG.md); the release notes for people who use the extension are +[`release-notes-1.x-en.md`](release-notes-1.x-en.md) and +[`release-notes-1.x-fr.md`](release-notes-1.x-fr.md). + +## Status against the specification phases (§14) + +| Phase | Content | State | +|-------|---------|-------| +| P1 | `core/` (parser, validator, config) + unit tests | Implemented | +| P1' | Programmatic-write spike (GitHub React + Azure DevOps) | Assumption validated in Chromium; remaining platform assumptions documented with their fallbacks (`spikes/p1-prime/README-fr.md`) | +| P2 | Extension `assist` on GitHub | Implemented | +| P3 | Azure DevOps adapter | Implemented, with the P1' fallbacks in place | +| P4 | Opt-in telemetry and the §12 indicators | **Partly implemented.** Opt-in counters ship: a label inserted through the extension, a diagnostic code shown, a selector degradation — with mode and repository, never free text —, sent only to a collection point declared by enterprise policy and accepted by the person. **The §12 indicators do not follow from them yet**: no event counts written or submitted comments, so the compliance and warning *rates* have no denominator, and a label typed or pasted by hand is missing from the distribution. Those events and the restitution remain to be built | +| P6 | `enforce` (send guard, §5.4) on a pilot repo, then rollout | **Blocked on P4** (§14). The send guard is implemented, and choosing the pilot and writing the rollback procedure can start now; switching the pilot to `enforce` waits for the §12 indicators. Rollback order: [`operations-fr.md`](operations-fr.md) | + +P5 (the verifier) and P0 (the baseline measurement, which only served an indicator that needed +the platform's API) are removed from the specification; their identifiers are not reused. +GitLab entered the scope later ([DEC0007](idr/DEC0007-gitlab-in-scope-en.md)); what its +adapter covers is in the [platforms](guide/platforms-en.md) page. + +## Other maintainer documents + +| Document | Content | +|---|---| +| [`architecture-fr.md`](architecture-fr.md) | The packages and what `core/` guarantees | +| [`operations-fr.md`](operations-fr.md) | Adoption path, prerequisites to `enforce`, rollback procedure | +| [`ca-matrix-fr.md`](ca-matrix-fr.md) | Each acceptance criterion and the tests that cover it | +| [`session-marker-rendering-fr.md`](session-marker-rendering-fr.md) | How the review-session marker is rendered | +| [`release-fr.md`](release-fr.md) | Cutting a release | +| [`store-listing-en.md`](store-listing-en.md), [`store-listing-fr.md`](store-listing-fr.md) | Draft of the store listing | +| [`store-permissions-justification-fr.md`](store-permissions-justification-fr.md) | Permission justification for the store review | +| [`idr/`](idr/README-en.md) | Important Decision Records | +| [`../A-FAIRE-fr.md`](../A-FAIRE-fr.md) | What remains to be done | diff --git a/docs/guide/configuration-en.md b/docs/guide/configuration-en.md new file mode 100644 index 00000000..72d2b98a --- /dev/null +++ b/docs/guide/configuration-en.md @@ -0,0 +1,290 @@ +# Configuration + +**Languages:** English (this file) | [Français](configuration-fr.md) + +The extension works with no configuration. A repository that wants its own labels, rules or +mode adds one file. + +## The repository file + +Put a `.conventional-comments.json` file at the root of the repository's **default branch**: + +```json +{ + "version": 1, + "mode": "assist" +} +``` + +Every key is optional: a key you leave out keeps the product default. The extension of every +reviewer reads this file from the pull request page, on their own session, without any token. + +[`.conventional-comments.example.json`](../../.conventional-comments.example.json) shows the +shape of every key. It is an example, **not** the product defaults: it lists only a handful of +labels and turns one warning off to illustrate an override. + +> On GitLab, the extension does not read the repository file yet: the product defaults apply +> there ([platforms](platforms-en.md)). + +## Where the values come from + +Three levels, the first that sets a key wins: + +1. the repository file, `.conventional-comments.json`; +2. the organisation's configuration, a JSON document of the same shape served by a URL; +3. the product defaults. + +Above them, an organisation can set a **floor** through the browser's enterprise policy: a +minimum mode and rules that no repository can relax. The URL of the organisation's +configuration also comes from that policy, never from a repository file +([deploying for an organisation](organization-en.md)). + +Your own [settings](settings-en.md) only cover the interface language, your shortcuts and the +order of the buttons. They never change the mode or the list of labels. + +### How levels combine + +| Key | A lower level… | +|---|---| +| `labels`, `decorations.known` | overrides the properties of an entry with the same `id`, and can add entries. It never removes one: to retire a label, set `"enabled": false`. | +| `severities`, `shortcuts.abbreviations` | overrides or adds entries one by one, without erasing the others. | +| `exemptUsers`, `allowlistPatterns`, `toolCommands` | adds to the list. It cannot remove what a higher level put there. | +| `mode`, `rules.*`, `scope.*` and the other single values | replaces the value. | + +So a repository that declares two labels still has all the shipped ones, plus or overriding +those two. + +### When a change takes effect + +A change applies to pull requests that are **already open**, as soon as the extension reads +it. The extension caches what it read for `configCacheTtlSeconds` (one hour by default), with +one exception: before it blocks a send, it always re-reads the configuration. A comment is +never blocked on a stale rule, and relaxing the mode lifts the blocking at the very next +attempt. + +Tightening a rule can therefore make comments non-compliant, or threads blocking, on every +open pull request at once. Tighten in `assist`, watch what the pill and the banner report, +then move to `enforce` ([modes and adoption](modes-and-adoption-en.md)). + +## Keys + +### `mode` + +`"off"`, `"assist"` (default) or `"enforce"`. See [modes and adoption](modes-and-adoption-en.md). + +### `labels` + +A list of labels, merged by `id` with the [shipped ones](labels-en.md). + +| Property | Meaning | Default for a label you create | +|---|---|---| +| `id` | The word typed before the colon. Letters only: `followup`, not `follow-up`. | required | +| `enabled` | `false` retires the label: it is no longer offered, and typing it is `E-UNKNOWN-LABEL`. | `true` | +| `blockingByDefault` | Whether the label blocks when no decoration says otherwise. | `false` | +| `alwaysNonBlocking` | `true` forbids `(blocking)` on this label. | `false` | +| `kind` | `"remark"` raises a point, `"reply"` answers one, `"status"` says where the review stands. It places the button in the toolbar and changes no verdict. | `"remark"` | +| `aliases` | Other spellings accepted in input, such as `["bug"]`. | none | +| `icon` | Shown on the badge. | none | +| `color` | Colour of the button and the badge, such as `"#C2410C"`. Check its contrast in light and dark themes. | none | +| `description` | Tooltip of the **badge**: what the comment means for whoever reads it. | shipped text, if any | +| `usage` | Tooltip of the **button**: when to use the label. Without it, the button shows `description`. | shipped text, if any | + +`description` and `usage` are shown as written, whatever the interface language. Written +empty (`""`), they remove the tooltip. + +**Add a label:** + +```json +{ "labels": [ { "id": "risk", "blockingByDefault": true, "icon": "⚠️", "color": "#C2410C", + "description": "A regression risk raised by the reviewer.", + "usage": "Flag a regression risk to assess before merging." } ] } +``` + +**Change a shipped label:** + +```json +{ "labels": [ { "id": "issue", "aliases": ["bug"] }, + { "id": "todo", "blockingByDefault": false }, + { "id": "quibble", "enabled": true }, + { "id": "typo", "enabled": false } ] } +``` + +Two active labels cannot share a name. An alias that repeats the `id` of another active label +is dropped, an alias carried by two labels is dropped from both, and each removal is reported +as a configuration notice. + +### `decorations` + +```json +{ "decorations": { + "allowFree": false, + "known": [ { "id": "security", "forces": null }, + { "id": "must-fix", "forces": "blocking" } ] } } +``` + +- `allowFree` (default `true`): whether a decoration outside `known` is accepted. At `false`, + an unknown decoration is `E-UNKNOWN-DECORATION`. +- `known`: decorations by `id`. `forces` is `"blocking"`, `"non-blocking"` or `null` for a + purely descriptive decoration. Shipped: `blocking`, `non-blocking`, `if-minor`. A decoration + whose `forces` is not `null` gets a segment in the toolbar. + +### `severities` + +The severity of a [diagnostic code](diagnostics-en.md): `"off"`, `"warn"` or `"error"`. +Default: empty, every code keeps its shipped severity. + +```json +{ "severities": { "W-MISSING-DECORATION": "off" } } +``` + +An `E-` code cannot go below `"warn"`. + +### `scope` + +| Key | Meaning | Default | +|---|---|---| +| `validateReplies` | Validate replies in a thread. At `false`, a reply gets no diagnostic, except a `decision`. | `false` | +| `validateReviewSummary` | Validate the body of a review submitted as a whole. Ignored on Azure DevOps, which has no such body. | `true` | + +Turning `validateReplies` on applies at once to open pull requests: every reply written +without a prefix becomes non-compliant. Let the team adopt the +[reply labels](labels-en.md#replying-to-a-point) first, require them afterwards. + +### `rules` + +| Key | Meaning | Default | +|---|---|---| +| `minSubjectLength` | Below it, `W-SUBJECT-TOO-SHORT`. | `5` | +| `maxSubjectLength` | Above it, `W-SUBJECT-TOO-LONG`. | `120` | +| `minDecisionSubjectLength` | Minimum length of the reason of a `decision`. | `20` | + +### `exemptUsers`, `allowlistPatterns`, `toolCommands` + +Three ways to leave comments out of validation. All three are **empty by default**. + +| Key | Exempts | Example | +|---|---|---| +| `exemptUsers` | Comments written by these accounts, compared by login, ignoring case. | `["dependabot[bot]", "github-actions[bot]"]` | +| `allowlistPatterns` | Comments whose **whole** body, trimmed, matches one of these regular expressions. | `["^LGTM$"]` | +| `toolCommands` | Comments that **start** with a command addressed to a tool. | `["/*", "@dependabot", "@codex"]` | + +`toolCommands` takes two kinds of entries, compared as exact strings: + +- `"/*"` recognises any slash command at the start of the body: `/rebase`, `/retest`, + `/azp run`… A path such as `/etc/hosts is wrong` is not taken for a command. +- an exact handle such as `"@dependabot"` recognises a mention of that account as the first + word. There is no wildcard for mentions: `@alice can you look at this?` is a review comment. + +A command cannot simply be given a label: most tools only read a command placed at the very +start of the comment. + +`allowlistPatterns` is limited to 50 patterns of 256 characters, with no nested quantifier; +a pattern outside these bounds is ignored and reported. Anchor patterns at both ends: +`^bors retry` would also exempt `bors retry is broken since yesterday`. + +An exempt comment has no label for the extension. A blocking remark written by an account in +`exemptUsers` is therefore **not counted** among the blocking threads. For an automated +reviewer, either leave it exempt and treat its remarks as advisory, or teach it the convention +([review skills](review-skills-en.md)). + +### `shortcuts.abbreviations` + +Abbreviations expanded by `Tab`, each mapped to the text inserted. See +[keyboard input](keyboard-input-en.md#abbreviations). + +### Display + +| Key | Meaning | Default | +|---|---|---| +| `language` | Interface language, `"en"` or `"fr"`, for those who set none in their settings. Without it, the extension follows the platform's language. | `null` | +| `badgeStyle` | `"pill"` or `"flat"`. | `"pill"` | +| `sessionIcon` | Icon of the review-session mention. | `"🤖"` | + +### Compatibility and cache + +| Key | Meaning | Default | +|---|---|---| +| `version` | Version of the configuration format. A file with a version the extension does not support makes it fall back on `assist`. | `1` | +| `coreMinVersion` | Minimum major version of the extension's rules engine this file needs. Same fallback. | `"1.0.0"` | +| `configCacheTtlSeconds` | How long the extension keeps what it read. | `3600` | + +### Keys that do nothing in a repository file + +- `configUrl` is ignored and reported: the address of the organisation's configuration only + comes from the enterprise policy. Otherwise a repository could designate the very document + meant to constrain it. +- `telemetry` cannot turn telemetry on: only the enterprise policy and each person's own + consent can ([privacy policy](../../PRIVACY.md)). + +## When the file is missing or wrong + +| Situation | What the extension does | +|---|---| +| No file | Uses the organisation's configuration, then the product defaults. This is normal, not an incident. | +| Invalid JSON, or an unusable value for a known key (`"mode": "banana"`) | Falls back on the last valid level and shows an *invalid configuration* notice with the faulty line. | +| An unknown key | Ignores that key, reports it, applies the rest. | +| The file cannot be reached | Falls back on the level below and shows *Configuration unread*: it assists and no longer blocks. | +| A newer `version` or `coreMinVersion` than the extension supports | Falls back on `assist`, or on the enterprise floor if it is stricter, and reports it. | + +A broken file never silently removes an enterprise floor. + +## Recipes + +**Stick to Conventional Comments.** Disable the six +[added labels](labels-en.md#sticking-to-conventional-comments). + +**Let bots and commands through on GitHub:** + +```json +{ + "exemptUsers": ["dependabot[bot]", "github-actions[bot]"], + "toolCommands": ["/*", "@dependabot", "@copilot", "@coderabbitai", "@codex", "@claude", + "@mergifyio", "@renovate", "@rustbot", "@bors"] +} +``` + +On a GitHub Enterprise Server where one of these handles is a person's account, leave it out. + +**Require labels on replies too:** + +```json +{ "scope": { "validateReplies": true } } +``` + +**Block non-compliant comments in this repository:** + +```json +{ "mode": "enforce" } +``` + +Read [modes and adoption](modes-and-adoption-en.md) first. + +## Upgrading + +**From a version without `toolCommands`.** Slash commands used to be exempted through a list +built into the GitHub adapter (`/azp`, `/rebase`). That list is gone and `toolCommands` is +empty by default: in `enforce` mode a `/rebase` is now rejected until the repository declares +it. Adding `"/*"` to `toolCommands` restores the exemption and widens it to every slash +command. + +**Retired keys.** `formatSeverity`, `overrideLabel`, `resolverOverrideGroup`, `activation` and +`docUrl` served a component that no longer exists +([DEC0010](../idr/DEC0010-the-extension-is-the-whole-product-en.md)). A file that still +carries them stays readable: each is ignored and reported. `"mode": "warn"` is read as +`"assist"`, with a notice. Remove them to clear the notices. + +**A label of your own called `thanks`, `done`, `ack`, `disagree`, `summary` or `reviewed`.** +Your entry now merges with the shipped label of the same name and inherits +`alwaysNonBlocking: true`, so `done (blocking):` becomes `E-CONFLICT`. Restore your label +with: + +```json +{ "labels": [ { "id": "done", "alwaysNonBlocking": false } ] } +``` + +A label of your own called `fixed`, `acknowledged` or `thx` keeps its name: the shipped alias +of the same name gives way, and the removal is reported as a notice. + +**Rules live in the extension, not in the file.** Two people running different versions of +the extension can apply different rules to the same file. `coreMinVersion` is the lever to +require a version. diff --git a/docs/guide/configuration-fr.md b/docs/guide/configuration-fr.md new file mode 100644 index 00000000..ea3127c8 --- /dev/null +++ b/docs/guide/configuration-fr.md @@ -0,0 +1,298 @@ +# Configuration + +**Langues :** [English](configuration-en.md) | Français (ce fichier) + +L'extension fonctionne sans aucune configuration. Un dépôt qui veut ses propres labels, ses +propres règles ou son propre mode ajoute un fichier. + +## Le fichier du dépôt + +Placez un fichier `.conventional-comments.json` à la racine de la **branche par défaut** du +dépôt : + +```json +{ + "version": 1, + "mode": "assist" +} +``` + +Toutes les clés sont facultatives : une clé que vous omettez garde la valeur par défaut du +produit. L'extension de chaque relecteur lit ce fichier depuis la page de la pull request, +avec sa propre session, sans aucun jeton. + +[`.conventional-comments.example.json`](../../.conventional-comments.example.json) montre la +forme de chaque clé. C'est un exemple, **pas** les valeurs par défaut du produit : il ne liste +qu'une poignée de labels et désactive un avertissement pour illustrer une surcharge. + +> Sur GitLab, l'extension ne lit pas encore le fichier du dépôt : les valeurs par défaut du +> produit s'y appliquent ([plateformes](platforms-fr.md)). + +## D'où viennent les valeurs + +Trois niveaux, le premier qui renseigne une clé l'emporte : + +1. le fichier du dépôt, `.conventional-comments.json` ; +2. la configuration d'organisation, un document JSON de même forme servi par une URL ; +3. les valeurs par défaut du produit. + +Au-dessus d'eux, une organisation peut fixer un **plancher** par la politique d'entreprise du +navigateur : un mode minimum et des règles qu'aucun dépôt ne peut assouplir. L'URL de la +configuration d'organisation vient elle aussi de cette politique, jamais d'un fichier de dépôt +([déployer pour une organisation](organization-fr.md)). + +Vos propres [réglages](settings-fr.md) ne couvrent que la langue de l'interface, vos +raccourcis et l'ordre des boutons. Ils ne changent jamais le mode ni la liste des labels. + +### Comment les niveaux se combinent + +| Clé | Un niveau inférieur… | +|---|---| +| `labels`, `decorations.known` | surcharge les propriétés d'une entrée de même `id`, et peut ajouter des entrées. Il n'en retire jamais : pour retirer un label, écrivez `"enabled": false`. | +| `severities`, `shortcuts.abbreviations` | surcharge ou ajoute des entrées une à une, sans effacer les autres. | +| `exemptUsers`, `allowlistPatterns`, `toolCommands` | ajoute à la liste. Il ne peut pas retirer ce qu'un niveau supérieur y a mis. | +| `mode`, `rules.*`, `scope.*` et les autres valeurs simples | remplace la valeur. | + +Un dépôt qui déclare deux labels dispose donc toujours de tous les labels livrés, auxquels ces +deux-là s'ajoutent ou qu'ils surchargent. + +### Quand un changement prend effet + +Un changement s'applique aux pull requests **déjà ouvertes**, dès que l'extension le lit. +L'extension garde en cache ce qu'elle a lu pendant `configCacheTtlSeconds` (une heure par +défaut), à une exception près : avant de bloquer un envoi, elle relit toujours la +configuration. Un commentaire n'est jamais bloqué sur une règle périmée, et assouplir le mode +lève le blocage dès la tentative suivante. + +Durcir une règle peut donc rendre des commentaires non conformes, ou des fils bloquants, sur +toutes les pull requests ouvertes à la fois. Durcissez en `assist`, regardez ce que signalent +la pastille et le bandeau, puis passez en `enforce` +([modes et adoption](modes-and-adoption-fr.md)). + +## Clés + +### `mode` + +`"off"`, `"assist"` (par défaut) ou `"enforce"`. Voir +[modes et adoption](modes-and-adoption-fr.md). + +### `labels` + +Une liste de labels, fusionnée par `id` avec les [labels livrés](labels-fr.md). + +| Propriété | Sens | Valeur par défaut pour un label que vous créez | +|---|---|---| +| `id` | Le mot tapé avant les deux-points. Des lettres seulement : `followup`, pas `follow-up`. | obligatoire | +| `enabled` | `false` retire le label : il n'est plus proposé, et le taper donne `E-UNKNOWN-LABEL`. | `true` | +| `blockingByDefault` | Indique si le label bloque quand aucune décoration ne dit le contraire. | `false` | +| `alwaysNonBlocking` | `true` interdit `(blocking)` sur ce label. | `false` | +| `kind` | `"remark"` soulève un point, `"reply"` y répond, `"status"` dit où en est la revue. Il place le bouton dans la barre d'outils et ne change aucun verdict. | `"remark"` | +| `aliases` | D'autres graphies acceptées à la saisie, comme `["bug"]`. | aucun | +| `icon` | Affichée sur le badge. | aucune | +| `color` | Couleur du bouton et du badge, comme `"#C2410C"`. Vérifiez son contraste en thème clair et en thème sombre. | aucune | +| `description` | Infobulle du **badge** : ce que le commentaire signifie pour la personne qui le lit. | texte livré, s'il existe | +| `usage` | Infobulle du **bouton** : quand utiliser le label. Sans elle, le bouton affiche `description`. | texte livré, s'il existe | + +`description` et `usage` s'affichent tels qu'ils sont écrits, quelle que soit la langue de +l'interface. Écrits vides (`""`), ils suppriment l'infobulle. + +**Ajouter un label :** + +```json +{ "labels": [ { "id": "risk", "blockingByDefault": true, "icon": "⚠️", "color": "#C2410C", + "description": "Un risque de régression soulevé par le relecteur.", + "usage": "Signaler un risque de régression à évaluer avant la fusion." } ] } +``` + +**Modifier un label livré :** + +```json +{ "labels": [ { "id": "issue", "aliases": ["bug"] }, + { "id": "todo", "blockingByDefault": false }, + { "id": "quibble", "enabled": true }, + { "id": "typo", "enabled": false } ] } +``` + +Deux labels actifs ne peuvent pas porter le même nom. Un alias qui reprend l'`id` d'un autre +label actif est écarté, un alias porté par deux labels est écarté des deux, et chaque retrait +est signalé par un avis de configuration. + +### `decorations` + +```json +{ "decorations": { + "allowFree": false, + "known": [ { "id": "security", "forces": null }, + { "id": "must-fix", "forces": "blocking" } ] } } +``` + +- `allowFree` (`true` par défaut) : indique si une décoration absente de `known` est acceptée. + À `false`, une décoration inconnue donne `E-UNKNOWN-DECORATION`. +- `known` : les décorations, par `id`. `forces` vaut `"blocking"`, `"non-blocking"` ou `null` + pour une décoration purement descriptive. Livrées : `blocking`, `non-blocking`, `if-minor`. + Une décoration dont `forces` n'est pas `null` reçoit un segment dans la barre d'outils. + +### `severities` + +La sévérité d'un [code de diagnostic](diagnostics-fr.md) : `"off"`, `"warn"` ou `"error"`. +Par défaut : vide, chaque code garde sa sévérité livrée. + +```json +{ "severities": { "W-MISSING-DECORATION": "off" } } +``` + +Un code `E-` ne peut pas descendre en dessous de `"warn"`. + +### `scope` + +| Clé | Sens | Valeur par défaut | +|---|---|---| +| `validateReplies` | Valider les réponses dans un fil. À `false`, une réponse ne reçoit aucun diagnostic, sauf une `decision`. | `false` | +| `validateReviewSummary` | Valider le corps d'une revue soumise en bloc. Ignorée sur Azure DevOps, où ce corps n'existe pas. | `true` | + +Activer `validateReplies` s'applique aussitôt aux pull requests ouvertes : toute réponse +écrite sans préfixe devient non conforme. Laissez d'abord l'équipe adopter les +[labels de réponse](labels-fr.md#répondre-à-un-point), exigez-les ensuite. + +### `rules` + +| Clé | Sens | Valeur par défaut | +|---|---|---| +| `minSubjectLength` | En dessous, `W-SUBJECT-TOO-SHORT`. | `5` | +| `maxSubjectLength` | Au-dessus, `W-SUBJECT-TOO-LONG`. | `120` | +| `minDecisionSubjectLength` | Longueur minimale du motif d'une `decision`. | `20` | + +### `exemptUsers`, `allowlistPatterns`, `toolCommands` + +Trois façons de laisser des commentaires hors de la validation. Les trois sont **vides par +défaut**. + +| Clé | Exempte | Exemple | +|---|---|---| +| `exemptUsers` | Les commentaires écrits par ces comptes, comparés par identifiant de connexion, sans tenir compte de la casse. | `["dependabot[bot]", "github-actions[bot]"]` | +| `allowlistPatterns` | Les commentaires dont le corps **entier**, espaces de bordure retirés, correspond à l'une de ces expressions régulières. | `["^LGTM$"]` | +| `toolCommands` | Les commentaires qui **commencent** par une commande adressée à un outil. | `["/*", "@dependabot", "@codex"]` | + +`toolCommands` accepte deux sortes d'entrées, comparées comme des chaînes exactes : + +- `"/*"` reconnaît toute commande slash en tête de corps : `/rebase`, `/retest`, + `/azp run`… Un chemin comme `/etc/hosts is wrong` n'est pas pris pour une commande. +- un handle exact comme `"@dependabot"` reconnaît une mention de ce compte en premier mot. + Il n'existe pas de joker pour les mentions : `@alice can you look at this?` est un + commentaire de revue. + +On ne peut pas simplement donner un label à une commande : la plupart des outils ne lisent +qu'une commande placée tout au début du commentaire. + +`allowlistPatterns` est limitée à 50 motifs de 256 caractères, sans quantificateur imbriqué ; +un motif hors de ces bornes est ignoré et signalé. Ancrez les motifs aux deux extrémités : +`^bors retry` exempterait aussi `bors retry is broken since yesterday`. + +Un commentaire exempté n'a pas de label pour l'extension. Une remarque bloquante écrite par un +compte de `exemptUsers` n'est donc **pas comptée** parmi les fils bloquants. Pour un relecteur +automatisé, soit vous le laissez exempté et vous tenez ses remarques pour consultatives, soit +vous lui apprenez la convention ([skills de revue](review-skills-fr.md)). + +### `shortcuts.abbreviations` + +Les abréviations développées par `Tab`, chacune associée au texte inséré. Voir +[saisie au clavier](keyboard-input-fr.md#abréviations). + +### Affichage + +| Clé | Sens | Valeur par défaut | +|---|---|---| +| `language` | Langue de l'interface, `"en"` ou `"fr"`, pour ceux qui n'en choisissent aucune dans leurs réglages. Sans elle, l'extension suit la langue de la plateforme. | `null` | +| `badgeStyle` | `"pill"` ou `"flat"`. | `"pill"` | +| `sessionIcon` | Icône de la mention de session de revue. | `"🤖"` | + +### Compatibilité et cache + +| Clé | Sens | Valeur par défaut | +|---|---|---| +| `version` | Version du format de configuration. Un fichier dont la version n'est pas prise en charge par l'extension la fait se replier sur `assist`. | `1` | +| `coreMinVersion` | Version majeure minimale du moteur de règles de l'extension dont ce fichier a besoin. Même repli. | `"1.0.0"` | +| `configCacheTtlSeconds` | Durée pendant laquelle l'extension garde ce qu'elle a lu. | `3600` | + +### Les clés sans effet dans un fichier de dépôt + +- `configUrl` est ignorée et signalée : l'adresse de la configuration d'organisation ne vient + que de la politique d'entreprise. Sinon, un dépôt pourrait désigner lui-même le document + censé le contraindre. +- `telemetry` ne peut pas activer la télémétrie : seuls la politique d'entreprise et le + consentement de chaque personne le peuvent + ([politique de confidentialité](../../PRIVACY.md)). + +## Quand le fichier est absent ou incorrect + +| Situation | Ce que fait l'extension | +|---|---| +| Aucun fichier | Utilise la configuration d'organisation, puis les valeurs par défaut du produit. C'est normal, ce n'est pas un incident. | +| JSON invalide, ou valeur inutilisable pour une clé connue (`"mode": "banana"`) | Se replie sur le dernier niveau valide et affiche un avis *configuration invalide* avec la ligne fautive. | +| Une clé inconnue | Ignore cette clé, la signale, applique le reste. | +| Le fichier est inaccessible | Se replie sur le niveau inférieur et affiche *Configuration non lue* : elle assiste et ne bloque plus. | +| Une `version` ou une `coreMinVersion` plus récente que ce que l'extension prend en charge | Se replie sur `assist`, ou sur le plancher d'entreprise s'il est plus strict, et le signale. | + +Un fichier cassé ne retire jamais un plancher d'entreprise en silence. + +## Recettes + +**S'en tenir à Conventional Comments.** Désactivez les six +[labels ajoutés](labels-fr.md#sen-tenir-à-conventional-comments). + +**Laisser passer les bots et les commandes sur GitHub :** + +```json +{ + "exemptUsers": ["dependabot[bot]", "github-actions[bot]"], + "toolCommands": ["/*", "@dependabot", "@copilot", "@coderabbitai", "@codex", "@claude", + "@mergifyio", "@renovate", "@rustbot", "@bors"] +} +``` + +Sur un GitHub Enterprise Server où l'un de ces handles est le compte d'une personne, +omettez-le. + +**Exiger des labels sur les réponses aussi :** + +```json +{ "scope": { "validateReplies": true } } +``` + +**Bloquer les commentaires non conformes dans ce dépôt :** + +```json +{ "mode": "enforce" } +``` + +Lisez d'abord [modes et adoption](modes-and-adoption-fr.md). + +## Mise à niveau + +**Depuis une version sans `toolCommands`.** Les commandes slash étaient auparavant exemptées +par une liste intégrée à l'adaptateur GitHub (`/azp`, `/rebase`). Cette liste a disparu et +`toolCommands` est vide par défaut : en mode `enforce`, un `/rebase` est désormais refusé tant +que le dépôt ne le déclare pas. Ajouter `"/*"` à `toolCommands` rétablit l'exemption et +l'étend à toutes les commandes slash. + +**Clés retirées.** `formatSeverity`, `overrideLabel`, `resolverOverrideGroup`, `activation` et +`docUrl` servaient un composant qui n'existe plus +([DEC0010](../idr/DEC0010-the-extension-is-the-whole-product-fr.md)). Un fichier qui les +porte encore reste lisible : chacune est ignorée et signalée. `"mode": "warn"` est lu comme +`"assist"`, avec un avis. Retirez-les pour faire disparaître les avis. + +**Un label à vous nommé `thanks`, `done`, `ack`, `disagree`, `summary` ou `reviewed`.** +Votre entrée fusionne désormais avec le label livré de même nom et hérite de +`alwaysNonBlocking: true`, si bien que `done (blocking):` devient `E-CONFLICT`. Rétablissez +votre label avec : + +```json +{ "labels": [ { "id": "done", "alwaysNonBlocking": false } ] } +``` + +Un label à vous nommé `fixed`, `acknowledged` ou `thx` garde son nom : l'alias livré de même +nom s'efface, et le retrait est signalé par un avis. + +**Les règles vivent dans l'extension, pas dans le fichier.** Deux personnes qui utilisent des +versions différentes de l'extension peuvent appliquer des règles différentes au même fichier. +`coreMinVersion` est le levier pour exiger une version. diff --git a/docs/guide/diagnostics-en.md b/docs/guide/diagnostics-en.md new file mode 100644 index 00000000..1761025a --- /dev/null +++ b/docs/guide/diagnostics-en.md @@ -0,0 +1,83 @@ +# Diagnostics + +**Languages:** English (this file) | [Français](diagnostics-fr.md) + +Every code the status pill can show, what triggers it and how to fix it. + +A code starting with `E-` is an **error**: the comment is non-compliant. A code starting with +`W-` is a **warning**: the comment stays compliant. Warnings never block a send; errors do, +and only in `enforce` mode ([modes](modes-and-adoption-en.md)). + +## How a comment is checked + +1. **The prefix is recognised**, or it is not. This step reports at most one problem and + stops there: nothing useful can be said about a prefix that could not be read. +2. **The content is checked**: decorations, subject, discussion. These checks add up, and the + pill lists them all, so that fixing one does not reveal the next. + +Each message answers what you just typed. `The build is broken since this morning` gets the +expected format (`E-NO-LABEL`). `attention: the build is broken` has the right shape and gets +the list of labels (`E-UNKNOWN-LABEL`). + +## Prefix + +| Code | Triggered by | Example | Fix | +|---|---|---|---| +| `E-NO-LABEL` | The comment does not start with `label: subject`. | `The build is broken` | Add a label: `issue: the build is broken`. | +| `E-MALFORMED-PREFIX` | The line starts with a known label, but the prefix is malformed. The message names the exact reason. | `issue (blocking: x`, `issue blocking): x`, `issue (blocking) x`, `issue:x` | Close or open the parenthesis, add the colon, add a space after the colon. One click when the correction can be computed. | +| `E-UNKNOWN-LABEL` | The shape is right, but the label is not in the configured list. | `isue: x` | Use one of the listed labels; the closest one is proposed. | +| `W-CASE` | The label is written in another case. | `Issue: x` | One click: `issue: x`. | + +## Decorations + +| Code | Triggered by | Example | Fix | +|---|---|---|---| +| `E-DECORATION-SYNTAX` | A decoration is not a word of letters, digits and hyphens: forbidden character, inner space, empty element, empty parentheses. | `(perf*)`, `(non blocking)`, `(blocking,,)`, `()` | Write `(non-blocking)`, remove the empty element. | +| `E-UNKNOWN-DECORATION` | An unknown decoration, in a repository that turned free decorations off (`decorations.allowFree: false`). | `issue (urgent): x` | Use a known decoration. | +| `E-CONFLICT` | `(blocking)` on a label that can never be blocking, or two decorations that contradict each other. | `nitpick (blocking): x`, `issue (blocking, non-blocking): x` | Keep one intention. | +| `W-DECORATION-STYLE` | Upper case, spaces inside the parentheses, a duplicate, or no space before the parenthesis. | `(BLOCKING)`, `( blocking )`, `issue(blocking): x` | One click to the canonical form. | + +## Subject + +| Code | Triggered by | Example | Fix | +|---|---|---|---| +| `E-EMPTY-SUBJECT` | Nothing after the colon. | `issue:` | Add a one-line summary. | +| `E-DECISION-SUBJECT` | A `decision` reply whose reason is shorter than `rules.minDecisionSubjectLength` (20 by default). | `decision: ok` | State the reason. | +| `W-SUBJECT-TOO-SHORT` | A subject shorter than `rules.minSubjectLength` (5 by default). | `issue: bug` | Say a little more. | +| `W-SUBJECT-TOO-LONG` | A subject longer than `rules.maxSubjectLength` (120 by default). | | Keep the summary on the first line, move the rest to the discussion. | + +## Discussion and context + +| Code | Triggered by | Example | Fix | +|---|---|---|---| +| `W-NO-DISCUSSION` | A **blocking** comment with nothing outside its prefix line. | `issue: memory leak` alone | Explain why the point must be addressed. | +| `W-MISSING-DECORATION` | A `suggestion` or a `question` without `(blocking)`, `(non-blocking)` or `(if-minor)`. A free decoration such as `(perf)` does not silence it. | `suggestion: extract a method` | Say whether the point blocks. | +| `W-NOT-BLOCKABLE` | A blocking comment written where no thread can be resolved, such as GitHub's general conversation. It will not be counted among the blocking threads. | `issue: please rebase` as a general comment | Write it on a line of the diff, or make it `(non-blocking)`. | +| `W-SESSION-MULTIPLE` | More than one `[session:…]` line: no session is designated. | | Keep a single marker line. | + +## Change a severity + +A repository can change the severity of a code with `severities` +([configuration](configuration-en.md#severities)): + +```json +{ "severities": { "W-MISSING-DECORATION": "off", "W-SUBJECT-TOO-LONG": "error" } } +``` + +Two limits hold whatever the configuration says: an `E-` code can be lowered to a warning but +never turned off, and `W-SESSION-MULTIPLE` can never become an error. + +## Configuration notices + +After the diagnostics, the pill can show notices about the configuration itself. They change +no verdict. + +| Notice | Meaning | +|---|---| +| Key ignored: it would relax the enterprise floor | The repository or the organisation wrote a value below what the enterprise policy allows. The floor applies. | +| Unknown or retired key, obsolete value | The key is ignored; the rest of the file applies. `"mode": "warn"` is read as `"assist"`. | +| Invalid configuration | The file cannot be parsed or a known key has an unusable value. The extension falls back on the last valid level: the organisation's configuration, then the product defaults. | +| Unsupported version | The file was written for a newer version of the extension. The extension falls back on `assist`, or on the enterprise floor if it is stricter. | + +*Configuration unread* is different: the extension could not reach the file at all. It then +assists without blocking ([FAQ](faq-en.md#the-pill-says-configuration-unread)). diff --git a/docs/guide/diagnostics-fr.md b/docs/guide/diagnostics-fr.md new file mode 100644 index 00000000..62e23ee1 --- /dev/null +++ b/docs/guide/diagnostics-fr.md @@ -0,0 +1,87 @@ +# Diagnostics + +**Langues :** [English](diagnostics-en.md) | Français (ce fichier) + +Tous les codes que la pastille peut afficher, ce qui les déclenche et comment les corriger. + +Un code qui commence par `E-` est une **erreur** : le commentaire est non conforme. Un code +qui commence par `W-` est un **avertissement** : le commentaire reste conforme. Les +avertissements ne bloquent jamais un envoi ; les erreurs le bloquent, et seulement en mode +`enforce` ([modes](modes-and-adoption-fr.md)). + +## Comment un commentaire est vérifié + +1. **Le préfixe est reconnu**, ou il ne l'est pas. Cette étape signale au plus un problème et + s'arrête là : on ne peut rien dire d'utile d'un préfixe qui n'a pas pu être lu. +2. **Le contenu est vérifié** : décorations, sujet, discussion. Ces vérifications + s'additionnent, et la pastille les liste toutes, pour qu'en corriger une ne révèle pas la + suivante. + +Chaque message répond à ce que vous venez de taper. `Le build est cassé depuis ce matin` +reçoit le format attendu (`E-NO-LABEL`). `attention: le build est cassé` a la bonne forme et +reçoit la liste des labels (`E-UNKNOWN-LABEL`). + +## Préfixe + +| Code | Déclenché par | Exemple | Correction | +|---|---|---|---| +| `E-NO-LABEL` | Le commentaire ne commence pas par `label: sujet`. | `Le build est cassé` | Ajoutez un label : `issue: le build est cassé`. | +| `E-MALFORMED-PREFIX` | La ligne commence par un label connu, mais le préfixe est mal formé. Le message nomme la raison exacte. | `issue (blocking: x`, `issue blocking): x`, `issue (blocking) x`, `issue:x` | Refermez ou ouvrez la parenthèse, ajoutez le deux-points, ajoutez une espace après le deux-points. Un clic quand la correction peut être calculée. | +| `E-UNKNOWN-LABEL` | La forme est bonne, mais le label n'est pas dans la liste configurée. | `isue: x` | Utilisez l'un des labels listés ; le plus proche est proposé. | +| `W-CASE` | Le label est écrit dans une autre casse. | `Issue: x` | Un clic : `issue: x`. | + +## Décorations + +| Code | Déclenché par | Exemple | Correction | +|---|---|---|---| +| `E-DECORATION-SYNTAX` | Une décoration n'est pas un mot de lettres, de chiffres et de traits d'union : caractère interdit, espace interne, élément vide, parenthèses vides. | `(perf*)`, `(non blocking)`, `(blocking,,)`, `()` | Écrivez `(non-blocking)`, retirez l'élément vide. | +| `E-UNKNOWN-DECORATION` | Une décoration inconnue, dans un dépôt qui a désactivé les décorations libres (`decorations.allowFree: false`). | `issue (urgent): x` | Utilisez une décoration connue. | +| `E-CONFLICT` | `(blocking)` sur un label qui ne peut jamais être bloquant, ou deux décorations qui se contredisent. | `nitpick (blocking): x`, `issue (blocking, non-blocking): x` | Ne gardez qu'une intention. | +| `W-DECORATION-STYLE` | Majuscules, espaces à l'intérieur des parenthèses, doublon, ou espace manquante avant la parenthèse. | `(BLOCKING)`, `( blocking )`, `issue(blocking): x` | Un clic vers la forme canonique. | + +## Sujet + +| Code | Déclenché par | Exemple | Correction | +|---|---|---|---| +| `E-EMPTY-SUBJECT` | Rien après le deux-points. | `issue:` | Ajoutez un résumé sur une ligne. | +| `E-DECISION-SUBJECT` | Une réponse `decision` dont le motif est plus court que `rules.minDecisionSubjectLength` (20 par défaut). | `decision: ok` | Énoncez le motif. | +| `W-SUBJECT-TOO-SHORT` | Un sujet plus court que `rules.minSubjectLength` (5 par défaut). | `issue: bug` | Dites-en un peu plus. | +| `W-SUBJECT-TOO-LONG` | Un sujet plus long que `rules.maxSubjectLength` (120 par défaut). | | Gardez le résumé sur la première ligne, déplacez le reste dans la discussion. | + +## Discussion et contexte + +| Code | Déclenché par | Exemple | Correction | +|---|---|---|---| +| `W-NO-DISCUSSION` | Un commentaire **bloquant** qui n'a rien en dehors de sa ligne de préfixe. | `issue: fuite mémoire` seul | Expliquez pourquoi le point doit être traité. | +| `W-MISSING-DECORATION` | Une `suggestion` ou une `question` sans `(blocking)`, `(non-blocking)` ni `(if-minor)`. Une décoration libre comme `(perf)` ne le fait pas taire. | `suggestion: extraire une méthode` | Dites si le point bloque. | +| `W-NOT-BLOCKABLE` | Un commentaire bloquant écrit là où aucun fil ne peut être résolu, comme la conversation générale de GitHub. Il ne sera pas compté parmi les fils bloquants. | `issue: merci de rebaser` en commentaire général | Écrivez-le sur une ligne du diff, ou rendez-le `(non-blocking)`. | +| `W-SESSION-MULTIPLE` | Plus d'une ligne `[session:…]` : aucune session n'est désignée. | | Ne gardez qu'une ligne de marqueur. | + +## Changer une sévérité + +Un dépôt peut changer la sévérité d'un code avec `severities` +([configuration](configuration-fr.md#severities)) : + +```json +{ "severities": { "W-MISSING-DECORATION": "off", "W-SUBJECT-TOO-LONG": "error" } } +``` + +Deux limites tiennent quoi que dise la configuration : un code `E-` peut être abaissé en +avertissement mais jamais désactivé, et `W-SESSION-MULTIPLE` ne peut jamais devenir une +erreur. + +## Avis de configuration + +Après les diagnostics, la pastille peut afficher des avis sur la configuration elle-même. Ils +ne changent aucun verdict. + +| Avis | Signification | +|---|---| +| Clé ignorée : elle assouplirait le plancher d'entreprise | Le dépôt ou l'organisation a écrit une valeur en dessous de ce que la politique d'entreprise autorise. Le plancher s'applique. | +| Clé inconnue ou retirée, valeur obsolète | La clé est ignorée ; le reste du fichier s'applique. `"mode": "warn"` est lu comme `"assist"`. | +| Configuration invalide | Le fichier ne peut pas être analysé, ou une clé connue a une valeur inutilisable. L'extension se replie sur le dernier niveau valide : la configuration de l'organisation, puis les valeurs par défaut du produit. | +| Version non prise en charge | Le fichier a été écrit pour une version plus récente de l'extension. L'extension se replie sur `assist`, ou sur le plancher d'entreprise s'il est plus strict. | + +*Configuration non lue* est un cas différent : l'extension n'a pas pu atteindre le fichier du +tout. Elle assiste alors sans bloquer +([FAQ](faq-fr.md#la-pastille-indique-une-configuration-non-lue)). diff --git a/docs/guide/faq-en.md b/docs/guide/faq-en.md new file mode 100644 index 00000000..bb91ad39 --- /dev/null +++ b/docs/guide/faq-en.md @@ -0,0 +1,121 @@ +# FAQ and troubleshooting + +**Languages:** English (this file) | [Français](faq-fr.md) + +## Nothing shows up + +### No toolbar appears on the pull request + +Check, in this order: + +1. **The domain is allowed.** Open the [settings page](settings-en.md): the domain must be + under *Configured domains*. If it is under *Unconfigured domains*, associate a platform. +2. **The page was reloaded** after you allowed the domain. +3. **You are in a comment field of a pull request.** The description of the pull request, + issues and work items are out of scope. +4. **On GitLab, you are in the Markdown editor.** The rich text editor is not handled; switch + back under the field ([platforms](platforms-en.md#gitlab)). +5. **The repository is not in `off` mode.** A repository can switch the extension off for + itself. + +If none of these explains it, open *Status* in the settings page: the journal lists what the +extension looked for and did not find. Download the diagnostic and attach it to an +[issue](https://github.com/reefact/conventional-comments-toolkit/issues), after reading it. + +### The pill says nothing in a reply + +Replies in a thread are not validated by default; only a `decision` reply is. The toolbar +still works there. A repository turns reply validation on with `scope.validateReplies` +([configuration](configuration-en.md#scope)). + +### A published comment shows a badge but its prefix is still in the text + +Expected. The prefix is hidden only when everything it says can be shown by badges and the +page's structure is one the extension knows. Otherwise it shows less rather than risk showing +something wrong: the badges sit above the comment and the text stays whole. + +### A colleague does not see the badges + +Badges are drawn by the extension, in the browser of whoever has it. The stored comment is +plain text, `issue (blocking): …`, readable by everyone. + +## Messages + +### The pill says *Configuration unread* + +The extension could not read the repository's or the organisation's configuration. It keeps +assisting with the rules it has and **does not block**, whatever the mode. + +- On **GitLab**, this is the normal state for now: the repository file is not read there. +- On GitHub and Azure DevOps, check that you are signed in and that the network reaches the + platform. For an organisation's configuration on another host, that host must be allowed. + +A repository with **no** configuration file does not cause this: an absent file is normal. + +### *Unknown label* on a label I have always used + +The repository's configuration disabled it, or never declared it. The message lists the +available labels. Aliases count: `bug:` works only if the repository declares `bug` as an +alias. + +### The send button is greyed out + +The repository is in `enforce` mode and the comment has an error. The pill names it, usually +with a one-click fix. If the configuration was just relaxed, try again: the extension re-reads +it before blocking and releases the button. + +### I changed the configuration file and nothing changed + +The extension caches what it read, one hour by default. It always re-reads before blocking a +send, so a rule is never enforced stale; the display can lag until the cache expires. + +### A direct shortcut does nothing + +- The label is disabled in this repository. +- You changed your shortcuts after the field was opened: they apply to the next field. +- On macOS, `Option` + letter may type a special character instead + ([known limit](keyboard-input-en.md#known-limit-on-macos)). + +## What the extension is and is not + +### Can someone get around `enforce`? + +Yes, and the product says so. The extension only acts in the browser where it is installed; +the platform's API, another browser or a disabled extension goes straight through. `enforce` +prevents the inattentive mistake, which is the common case +([modes](modes-and-adoption-en.md#what-enforce-does-not-do)). + +### Does it prevent a merge while blocking threads are open? + +No. The banner reports them. To gate merges, use your platform's own setting, such as +required conversation resolution. + +### Does `reviewed` approve the pull request? + +No. It says your review is over. Approval stays with the platform's own control, and the +extension does not count `reviewed`. + +### Are `done`, `ack`, `thanks`… part of Conventional Comments? + +No. They are additions of this extension, enabled by default, that a repository can disable +([labels](labels-en.md#labels-that-are-not-part-of-conventional-comments)). + +### What leaves my browser? + +No comment, code or diff content, ever. The extension reads the configuration file of the +repository you are looking at, on your own session; it stores no token. Your language and +shortcuts sync through your browser if its sync is on. Telemetry is off unless your +organisation declares an endpoint **and** you agree. The details are in the +[privacy policy](../../PRIVACY.md). + +### Does it check commit messages, or the quality of my comment? + +Neither. Commit messages are another convention (Conventional Commits). And the extension +checks the **form** of a comment, never whether it is right or kind. + +## Turning it off + +- **For yourself, on one platform:** withdraw the domain in the settings page. +- **For a repository:** `{ "mode": "off" }` in its `.conventional-comments.json`, if your + organisation's floor allows it. +- **Entirely:** disable or remove the extension from your browser's extensions page. diff --git a/docs/guide/faq-fr.md b/docs/guide/faq-fr.md new file mode 100644 index 00000000..99c60907 --- /dev/null +++ b/docs/guide/faq-fr.md @@ -0,0 +1,129 @@ +# FAQ et dépannage + +**Langues :** [English](faq-en.md) | Français (ce fichier) + +## Rien ne s'affiche + +### Aucune barre d'outils n'apparaît sur la pull request + +Vérifiez, dans cet ordre : + +1. **Le domaine est autorisé.** Ouvrez la [page de réglages](settings-fr.md) : le domaine + doit figurer sous *Domaines configurés*. S'il figure sous *Domaines non configurés*, + associez-lui une plateforme. +2. **La page a été rechargée** après l'autorisation du domaine. +3. **Vous êtes dans un champ de commentaire d'une pull request.** La description de la pull + request, les issues et les work items sont hors périmètre. +4. **Sur GitLab, vous êtes dans l'éditeur Markdown.** L'éditeur de texte enrichi n'est pas + géré ; rebasculez sous le champ ([plateformes](platforms-fr.md#gitlab)). +5. **Le dépôt n'est pas en mode `off`.** Un dépôt peut désactiver l'extension pour lui-même. + +Si rien de tout cela ne l'explique, ouvrez *État* dans la page de réglages : le journal liste +ce que l'extension a cherché sans le trouver. Téléchargez le diagnostic et joignez-le à une +[issue](https://github.com/reefact/conventional-comments-toolkit/issues), après l'avoir relu. + +### La pastille ne dit rien dans une réponse + +Les réponses dans un fil ne sont pas validées par défaut ; seule une réponse `decision` l'est. +La barre d'outils y fonctionne quand même. Un dépôt active la validation des réponses avec +`scope.validateReplies` ([configuration](configuration-fr.md#scope)). + +### Un commentaire publié affiche un badge mais son préfixe est toujours dans le texte + +C'est attendu. Le préfixe n'est masqué que si tout ce qu'il dit peut être montré par des +badges et si la structure de la page est de celles que l'extension connaît. Sinon, elle en +montre moins plutôt que de risquer de montrer quelque chose de faux : les badges se placent +au-dessus du commentaire et le texte reste entier. + +### Un collègue ne voit pas les badges + +Les badges sont dessinés par l'extension, dans le navigateur de qui l'a installée. Le +commentaire stocké est du texte brut, `issue (blocking): …`, lisible par tout le monde. + +## Messages + +### La pastille indique une configuration non lue + +L'extension n'a pas pu lire la configuration du dépôt ou de l'organisation. Elle continue +d'assister avec les règles qu'elle a et **ne bloque pas**, quel que soit le mode. + +- Sur **GitLab**, c'est l'état normal pour l'instant : le fichier du dépôt n'y est pas lu. +- Sur GitHub et Azure DevOps, vérifiez que vous êtes connecté et que le réseau atteint la + plateforme. Pour une configuration d'organisation placée sur un autre hôte, cet hôte doit + être autorisé. + +Un dépôt **sans** fichier de configuration ne provoque pas ce message : un fichier absent est +normal. + +### *Label inconnu* sur un label que j'ai toujours utilisé + +La configuration du dépôt l'a désactivé, ou ne l'a jamais déclaré. Le message liste les +labels disponibles. Les alias comptent : `bug:` ne fonctionne que si le dépôt déclare `bug` +comme alias. + +### Le bouton d'envoi est grisé + +Le dépôt est en mode `enforce` et le commentaire comporte une erreur. La pastille la nomme, +en général avec une correction en un clic. Si la configuration vient d'être assouplie, +réessayez : l'extension la relit avant de bloquer et libère le bouton. + +### J'ai modifié le fichier de configuration et rien n'a changé + +L'extension garde en cache ce qu'elle a lu, une heure par défaut. Elle relit toujours avant +de bloquer un envoi, si bien qu'une règle périmée n'est jamais imposée ; l'affichage peut +être en retard jusqu'à l'expiration du cache. + +### Un raccourci direct ne fait rien + +- Le label est désactivé dans ce dépôt. +- Vous avez changé vos raccourcis après l'ouverture du champ : ils s'appliquent au champ + suivant. +- Sur macOS, `Option` + lettre peut taper un caractère spécial à la place + ([limite connue](keyboard-input-fr.md#limite-connue-sur-macos)). + +## Ce que l'extension est et n'est pas + +### Peut-on contourner `enforce` ? + +Oui, et le produit le dit. L'extension n'agit que dans le navigateur où elle est installée ; +l'API de la plateforme, un autre navigateur ou une extension désactivée passent tout droit. +`enforce` empêche l'erreur d'inattention, qui est le cas courant +([modes](modes-and-adoption-fr.md#ce-que-enforce-ne-fait-pas)). + +### Empêche-t-elle une fusion tant que des fils bloquants sont ouverts ? + +Non. Le bandeau les signale. Pour conditionner les fusions, utilisez le réglage de votre +plateforme, comme la résolution obligatoire des conversations. + +### `reviewed` approuve-t-il la pull request ? + +Non. Il dit que votre revue est terminée. L'approbation reste au contrôle de la plateforme, +et l'extension ne compte pas les `reviewed`. + +### `done`, `ack`, `thanks`… font-ils partie de Conventional Comments ? + +Non. Ce sont des ajouts de cette extension, activés par défaut, qu'un dépôt peut désactiver +([labels](labels-fr.md#les-labels-qui-ne-font-pas-partie-de-conventional-comments)). + +### Qu'est-ce qui sort de mon navigateur ? + +Aucun contenu de commentaire, de code ou de diff, jamais. L'extension lit le fichier de +configuration du dépôt que vous consultez, avec votre propre session ; elle ne stocke aucun +jeton. Votre langue et vos raccourcis se synchronisent par votre navigateur si sa +synchronisation est activée. La télémétrie est désactivée, sauf si votre organisation déclare +un point de collecte **et** que vous donnez votre accord. Le détail est dans la +[politique de confidentialité](../../PRIVACY.md). + +### Vérifie-t-elle les messages de commit, ou la qualité de mon commentaire ? + +Ni l'un ni l'autre. Les messages de commit relèvent d'une autre convention (Conventional +Commits). Et l'extension vérifie la **forme** d'un commentaire, jamais s'il est juste ou +bienveillant. + +## La désactiver + +- **Pour vous, sur une plateforme :** retirez le domaine dans la page de réglages. +- **Pour un dépôt :** `{ "mode": "off" }` dans son `.conventional-comments.json`, si le + plancher de votre organisation le permet. +- **Entièrement :** désactivez ou supprimez l'extension depuis la page des extensions de + votre navigateur. diff --git a/docs/guide/getting-started-en.md b/docs/guide/getting-started-en.md new file mode 100644 index 00000000..a6dd9244 --- /dev/null +++ b/docs/guide/getting-started-en.md @@ -0,0 +1,92 @@ +# Getting started + +**Languages:** English (this file) | [Français](getting-started-fr.md) + +Ten minutes from nothing installed to a first review comment written with the toolbar. + +## What you need + +- Chrome, Edge or another Chromium browser, or Firefox 128 or later. +- A pull request you can comment on, on GitHub, Azure DevOps or GitLab + ([what works on which platform](platforms-en.md)). + +Nothing else: no account, no token, no server. + +## 1. Install the extension + +Every release carries the extension as a ready-to-load archive, one for Chromium browsers and +one for Firefox. + +1. Open the [releases page](https://github.com/reefact/conventional-comments-toolkit/releases) + and download `conventional-comments-toolkit--chromium.zip` (or `-firefox.zip`). +2. Unzip it somewhere you will keep. The browser re-reads that folder at every start, so + deleting it disables the extension. +3. Load it: + - **Chrome, Edge:** open `chrome://extensions`, turn on **Developer mode**, click + **Load unpacked** and pick the unzipped folder, the one that directly contains + `manifest.json`. + - **Firefox:** open `about:debugging#/runtime/this-firefox`, click **Load Temporary + Add-on** and pick the `manifest.json` of the unzipped folder. Firefox removes a temporary + add-on when it closes. + +An extension loaded this way does not update itself: a new version means downloading and +loading it again. To build the extension from source instead, follow the +[step-by-step build guide](../extension-setup-en.md). + +## 2. Allow your platform + +The extension's settings page opens by itself after the installation, with a short guided +tour. You can reopen it at any time by clicking the extension's icon in the browser toolbar. + +**The extension is inactive everywhere until you allow a domain.** It asks for no site access +at installation; you grant it one domain at a time. + +- Under **Known domains**, click the platform you use: GitHub.com, Azure DevOps Services + (`dev.azure.com`) or GitLab.com. The browser asks you to confirm. +- For a host of your own (GitHub Enterprise Server, Azure DevOps Server, a + `visualstudio.com` organisation, GitLab Self-Managed), type its domain under **Other + domains** and choose the platform that serves it **before** clicking **Allow**. + +The domain then appears under **Configured domains**, where you can withdraw the access at +any time. The [settings page](settings-en.md) guide describes the rest of that screen. + +## 3. Write your first comment + +Open a pull request on the domain you allowed, reload the page if it was already open, and +click into the field of a **new** comment. Replies in a thread are not validated by default, so +the pill stays silent there. + +1. A **toolbar** appears with one button per label: `praise`, `nitpick`, `suggestion`, + `issue`… +2. Type your remark, for example `this name does not say what the variable holds`. +3. A **status pill** under the field says the comment is non-compliant: it has no label yet. +4. Click **nitpick** in the toolbar. The comment becomes: + + ```text + nitpick: this name does not say what the variable holds + ``` + + The pill turns to *Compliant*. +5. Publish the comment as usual. Once published, its label is shown as a coloured badge. + +That is the whole loop: write, pick a label, publish. + +## What the extension does by default + +- It **assists and never blocks**. The default mode is `assist`: a non-compliant comment is + flagged and still goes out. Blocking is a choice a team makes for a repository + ([modes and adoption](modes-and-adoption-en.md)). +- It works **without any configuration file**. A repository that wants its own labels or + rules adds a `.conventional-comments.json` file ([configuration](configuration-en.md)). +- **No comment, code or diff content leaves your browser** ([privacy policy](../../PRIVACY.md)). + +## Where to go next + +| To… | Read | +|---|---| +| know every part of the toolbar, the pill, the badges and the banner | [Writing review comments](writing-comments-en.md) | +| write labels without the mouse | [Keyboard input](keyboard-input-en.md) | +| choose the right label | [Labels and decorations](labels-en.md) | +| understand a message of the pill | [Diagnostics](diagnostics-en.md) | +| set the rules for your repository | [Configuration](configuration-en.md) | +| find out why something does not show up | [FAQ and troubleshooting](faq-en.md) | diff --git a/docs/guide/getting-started-fr.md b/docs/guide/getting-started-fr.md new file mode 100644 index 00000000..4b324e5b --- /dev/null +++ b/docs/guide/getting-started-fr.md @@ -0,0 +1,98 @@ +# Premiers pas + +**Langues :** [English](getting-started-en.md) | Français (ce fichier) + +Dix minutes pour passer de rien d'installé à un premier commentaire de revue écrit avec la +barre d'outils. + +## Ce qu'il vous faut + +- Chrome, Edge ou un autre navigateur Chromium, ou Firefox 128 ou plus récent. +- Une pull request que vous pouvez commenter, sur GitHub, Azure DevOps ou GitLab + ([ce qui fonctionne sur quelle plateforme](platforms-fr.md)). + +Rien d'autre : ni compte, ni jeton, ni serveur. + +## 1. Installer l'extension + +Chaque release fournit l'extension sous forme d'archive prête à charger, une pour les +navigateurs Chromium et une pour Firefox. + +1. Ouvrez la [page des releases](https://github.com/reefact/conventional-comments-toolkit/releases) + et téléchargez `conventional-comments-toolkit--chromium.zip` (ou `-firefox.zip`). +2. Décompressez-la dans un dossier que vous garderez. Le navigateur relit ce dossier à chaque + démarrage : le supprimer désactive l'extension. +3. Chargez-la : + - **Chrome, Edge :** ouvrez `chrome://extensions`, activez le **Mode développeur**, cliquez + sur **Charger l'extension non empaquetée** et choisissez le dossier décompressé, celui + qui contient directement `manifest.json`. + - **Firefox :** ouvrez `about:debugging#/runtime/this-firefox`, cliquez sur **Charger un + module temporaire** et choisissez le `manifest.json` du dossier décompressé. Firefox + retire un module temporaire à sa fermeture. + +Une extension chargée de cette façon ne se met pas à jour toute seule : pour une nouvelle +version, il faut la télécharger et la charger à nouveau. Pour construire l'extension depuis +les sources, suivez plutôt le [guide de construction pas à pas](../extension-setup-fr.md). + +## 2. Autoriser votre plateforme + +La page de réglages de l'extension s'ouvre d'elle-même après l'installation, avec une courte +visite guidée. Vous pouvez la rouvrir à tout moment en cliquant sur l'icône de l'extension +dans la barre d'outils du navigateur. + +**L'extension est inactive partout tant que vous n'avez pas autorisé un domaine.** Elle ne +demande aucun accès aux sites à l'installation ; vous l'accordez un domaine à la fois. + +- Sous **Domaines connus**, cliquez sur la plateforme que vous utilisez : GitHub.com, Azure + DevOps Services (`dev.azure.com`) ou GitLab.com. Le navigateur vous demande de confirmer. +- Pour un hôte qui vous est propre (GitHub Enterprise Server, Azure DevOps Server, une + organisation `visualstudio.com`, GitLab Self-Managed), saisissez son domaine sous **Autres + domaines** et choisissez la plateforme qui le sert **avant** de cliquer sur **Autoriser**. + +Le domaine apparaît alors sous **Domaines configurés**, où vous pouvez retirer l'accès à tout +moment. Le guide de la [page de réglages](settings-fr.md) décrit le reste de cet écran. + +## 3. Écrire votre premier commentaire + +Ouvrez une pull request sur le domaine que vous avez autorisé, rechargez la page si elle +était déjà ouverte, et cliquez dans le champ d'un **nouveau** commentaire. Les réponses dans +un fil ne sont pas validées par défaut : la pastille y reste donc muette. + +1. Une **barre d'outils** apparaît, avec un bouton par label : `praise`, `nitpick`, + `suggestion`, `issue`… +2. Saisissez votre remarque, par exemple `ce nom ne dit pas ce que contient la variable`. +3. Une **pastille de validation**, sous le champ, indique que le commentaire est non + conforme : il n'a pas encore de label. +4. Cliquez sur **nitpick** dans la barre d'outils. Le commentaire devient : + + ```text + nitpick: ce nom ne dit pas ce que contient la variable + ``` + + La pastille passe à *Conforme*. +5. Publiez le commentaire comme d'habitude. Une fois publié, son label s'affiche sous la + forme d'un badge coloré. + +Voilà toute la boucle : écrire, choisir un label, publier. + +## Ce que l'extension fait par défaut + +- Elle **assiste et ne bloque jamais**. Le mode par défaut est `assist` : un commentaire non + conforme est signalé et part quand même. Bloquer est un choix qu'une équipe fait pour un + dépôt ([modes et adoption](modes-and-adoption-fr.md)). +- Elle fonctionne **sans aucun fichier de configuration**. Un dépôt qui veut ses propres + labels ou ses propres règles ajoute un fichier `.conventional-comments.json` + ([configuration](configuration-fr.md)). +- **Aucun contenu de commentaire, de code ou de diff ne quitte votre navigateur** + ([politique de confidentialité](../../PRIVACY.md)). + +## Pour aller plus loin + +| Pour… | Lisez | +|---|---| +| connaître chaque partie de la barre d'outils, de la pastille, des badges et du bandeau | [Écrire des commentaires de revue](writing-comments-fr.md) | +| écrire les labels sans la souris | [Saisie au clavier](keyboard-input-fr.md) | +| choisir le bon label | [Labels et décorations](labels-fr.md) | +| comprendre un message de la pastille | [Diagnostics](diagnostics-fr.md) | +| fixer les règles de votre dépôt | [Configuration](configuration-fr.md) | +| comprendre pourquoi quelque chose ne s'affiche pas | [FAQ et dépannage](faq-fr.md) | diff --git a/docs/guide/keyboard-input-en.md b/docs/guide/keyboard-input-en.md new file mode 100644 index 00000000..bedbc2e4 --- /dev/null +++ b/docs/guide/keyboard-input-en.md @@ -0,0 +1,147 @@ +# Keyboard input + +**Languages:** English (this file) | [Français](keyboard-input-fr.md) + +Three ways to write a prefix without touching the mouse. They complement the toolbar; all +three produce exactly the text a click would. + +| Way | You type | Who sets it | +|---|---|---| +| [Completion list](#completion-list) | `/` or `:` in an empty field | Nobody: it lists the active labels | +| [Abbreviations](#abbreviations) | `?ib` then `Tab` | The team, in the repository's configuration | +| [Direct shortcuts](#direct-shortcuts) | `Alt+I` | You, in the extension's settings | + +## Completion list + +In an **empty** comment field, type `/` or `:`. A list of the active labels opens and narrows +as you type. + +```text +:su +``` + +lists `suggestion` and `summary`. `↑` and `↓` move through the list, `Enter` or `Tab` accepts +the selected label, `Esc` closes the list. Accepting `suggestion` leaves: + +```text +suggestion: +``` + +with the caret after the space, ready for the subject. The list follows the order of the +toolbar buttons, your personal order included. + +## Abbreviations + +Type an abbreviation, then press `Tab`: it expands into a full prefix, decoration included. + +```text +?ib +``` + +then `Tab` gives: + +```text +issue (blocking): +``` + +An abbreviation expands wherever the caret is, so it also works after a quotation or a line +of context. + +### Shipped abbreviations + +| Abbreviation | Expands to | | Abbreviation | Expands to | +|---|---|---|---|---| +| `?i` | `issue: ` | | `?ch` | `chore: ` | +| `?ib` | `issue (blocking): ` | | `?ty` | `typo: ` | +| `?su` | `suggestion: ` | | `?po` | `polish: ` | +| `?ni` | `nitpick: ` | | `?qui` | `quibble: ` | +| `?no` | `note: ` | | `?sum` | `summary: ` | +| `?pr` | `praise: ` | | `?r` | `reviewed: ` | +| `?to` | `todo: ` | | `?thx` | `thanks: ` | +| `?th` | `thought: ` | | `?do` | `done: ` | +| `?que` | `question: ` | | `?a` | `ack: ` | +| `?de` | `decision: ` | | `?di` | `disagree: ` | + +An abbreviation takes as many letters as it needs to name one label: two tell `nitpick` from +`note`, three are needed for `question` and `quibble`. Since the expansion waits for `Tab`, +`?i` and `?ib` can coexist. + +A shipped abbreviation only expands to an **active** label. `?qui` does nothing until the +repository enables `quibble`, and `?do` does nothing in a repository that disabled `done`. + +### Add your own + +The table belongs to the team. It lives in the repository's `.conventional-comments.json`, +under `shortcuts.abbreviations`. Each entry maps an abbreviation to the text inserted, colon +and space included: + +```json +{ + "shortcuts": { + "abbreviations": { + "?sec": "issue (blocking, security): ", + "?snb": "suggestion (non-blocking): " + } + } +} +``` + +Your entries are added to the shipped ones; an entry with the same abbreviation redefines it +([configuration](configuration-en.md)). + +## Direct shortcuts + +A key combination inserts a label straight into the comment you are writing. + +| Shortcut | Label | | Shortcut | Label | +|---|---|---|---|---| +| `Alt+I` | `issue` | | `Alt+Q` | `question` | +| `Alt+S` | `suggestion` | | `Alt+P` | `praise` | +| `Alt+N` | `nitpick` | | `Alt+C` | `chore` | +| `Alt+T` | `todo` | | `Alt+D` | `decision` | + +You typed: + +```text +this name does not say what the variable holds +``` + +`Alt+N` gives: + +```text +nitpick: this name does not say what the variable holds +``` + +Changed your mind? `Alt+I` **replaces** the label instead of adding a second one: + +```text +issue: this name does not say what the variable holds +``` + +A decoration already written stays: on `nitpick (non-blocking): …`, a shortcut changes the +label and keeps `(non-blocking)`. A shortcut to a label the repository disabled does nothing. + +### Change them + +Direct shortcuts are a personal preference. In the [settings page](settings-en.md), under +*Local preferences* → *Direct shortcuts*, write one shortcut per line: + +```text +Alt+R=reviewed +Alt+D= +``` + +- `Alt+R=reviewed` adds a shortcut. +- `Alt+D=`, with no label, disables the shipped `Alt+D`. +- The shipped shortcuts you do not mention stay as they are. + +A shortcut is `Alt` plus one letter, and its label is written by its identifier (`reviewed`, +not an alias). The preference follows you through your browser's sync, and applies to the next +comment field that opens, not to those already open. + +### Known limit on macOS + +The extension recognises a shortcut by the character the key produces. On macOS, `Option` +plus a letter usually types a special character instead of the letter, so a direct shortcut +may not fire there. This has not been measured on a Mac. The completion list and the +abbreviations do not depend on `Alt` and are not affected. diff --git a/docs/guide/keyboard-input-fr.md b/docs/guide/keyboard-input-fr.md new file mode 100644 index 00000000..ea3ceff2 --- /dev/null +++ b/docs/guide/keyboard-input-fr.md @@ -0,0 +1,152 @@ +# Saisie au clavier + +**Langues :** [English](keyboard-input-en.md) | Français (ce fichier) + +Trois façons d'écrire un préfixe sans toucher la souris. Elles complètent la barre d'outils ; +toutes trois produisent exactement le texte qu'un clic produirait. + +| Façon | Vous saisissez | Qui la règle | +|---|---|---| +| [Liste de complétion](#liste-de-complétion) | `/` ou `:` dans un champ vide | Personne : elle liste les labels actifs | +| [Abréviations](#abréviations) | `?ib` puis `Tab` | L'équipe, dans la configuration du dépôt | +| [Raccourcis directs](#raccourcis-directs) | `Alt+I` | Vous, dans les réglages de l'extension | + +## Liste de complétion + +Dans un champ de commentaire **vide**, saisissez `/` ou `:`. Une liste des labels actifs +s'ouvre et se resserre au fil de la saisie. + +```text +:su +``` + +liste `suggestion` et `summary`. `↑` et `↓` parcourent la liste, `Entrée` ou `Tab` accepte le +label sélectionné, `Échap` ferme la liste. Accepter `suggestion` laisse : + +```text +suggestion: +``` + +avec le curseur après l'espace, prêt pour le sujet. La liste suit l'ordre des boutons de la +barre d'outils, votre ordre personnel compris. + +## Abréviations + +Saisissez une abréviation, puis appuyez sur `Tab` : elle se développe en un préfixe complet, +décoration comprise. + +```text +?ib +``` + +puis `Tab` donne : + +```text +issue (blocking): +``` + +Une abréviation se développe là où se trouve le curseur : elle fonctionne donc aussi après +une citation ou une ligne de contexte. + +### Abréviations livrées + +| Abréviation | Se développe en | | Abréviation | Se développe en | +|---|---|---|---|---| +| `?i` | `issue: ` | | `?ch` | `chore: ` | +| `?ib` | `issue (blocking): ` | | `?ty` | `typo: ` | +| `?su` | `suggestion: ` | | `?po` | `polish: ` | +| `?ni` | `nitpick: ` | | `?qui` | `quibble: ` | +| `?no` | `note: ` | | `?sum` | `summary: ` | +| `?pr` | `praise: ` | | `?r` | `reviewed: ` | +| `?to` | `todo: ` | | `?thx` | `thanks: ` | +| `?th` | `thought: ` | | `?do` | `done: ` | +| `?que` | `question: ` | | `?a` | `ack: ` | +| `?de` | `decision: ` | | `?di` | `disagree: ` | + +Une abréviation prend autant de lettres qu'il lui en faut pour désigner un seul label : deux +distinguent `nitpick` de `note`, il en faut trois pour `question` et `quibble`. Comme le +développement attend `Tab`, `?i` et `?ib` peuvent coexister. + +Une abréviation livrée ne se développe qu'en un label **actif**. `?qui` ne fait rien tant que +le dépôt n'active pas `quibble`, et `?do` ne fait rien dans un dépôt qui a désactivé `done`. + +### Ajouter les vôtres + +La table appartient à l'équipe. Elle vit dans le fichier `.conventional-comments.json` du +dépôt, sous `shortcuts.abbreviations`. Chaque entrée associe une abréviation au texte inséré, +deux-points et espace compris : + +```json +{ + "shortcuts": { + "abbreviations": { + "?sec": "issue (blocking, security): ", + "?snb": "suggestion (non-blocking): " + } + } +} +``` + +Vos entrées s'ajoutent à celles qui sont livrées ; une entrée portant la même abréviation la +redéfinit ([configuration](configuration-fr.md)). + +## Raccourcis directs + +Une combinaison de touches insère directement un label dans le commentaire que vous êtes en +train d'écrire. + +| Raccourci | Label | | Raccourci | Label | +|---|---|---|---|---| +| `Alt+I` | `issue` | | `Alt+Q` | `question` | +| `Alt+S` | `suggestion` | | `Alt+P` | `praise` | +| `Alt+N` | `nitpick` | | `Alt+C` | `chore` | +| `Alt+T` | `todo` | | `Alt+D` | `decision` | + +Vous avez saisi : + +```text +ce nom ne dit pas ce que contient la variable +``` + +`Alt+N` donne : + +```text +nitpick: ce nom ne dit pas ce que contient la variable +``` + +Vous avez changé d'avis ? `Alt+I` **remplace** le label au lieu d'en ajouter un second : + +```text +issue: ce nom ne dit pas ce que contient la variable +``` + +Une décoration déjà écrite reste : sur `nitpick (non-blocking): …`, un raccourci change le +label et garde `(non-blocking)`. Un raccourci vers un label que le dépôt a désactivé ne fait +rien. + +### Les modifier + +Les raccourcis directs sont une préférence personnelle. Dans la +[page de réglages](settings-fr.md), sous *Préférences locales* → *Raccourcis directs*, +écrivez un raccourci par ligne : + +```text +Alt+R=reviewed +Alt+D= +``` + +- `Alt+R=reviewed` ajoute un raccourci. +- `Alt+D=`, sans label, désactive le raccourci livré `Alt+D`. +- Les raccourcis livrés que vous ne mentionnez pas restent tels quels. + +Un raccourci, c'est `Alt` plus une lettre, et son label s'écrit par son identifiant +(`reviewed`, pas un alias). La préférence vous suit grâce à la synchronisation de votre +navigateur, et s'applique au prochain champ de commentaire qui s'ouvre, pas à ceux qui sont +déjà ouverts. + +### Limite connue sur macOS + +L'extension reconnaît un raccourci au caractère que la touche produit. Sur macOS, `Option` +plus une lettre saisit en général un caractère spécial au lieu de la lettre : un raccourci +direct peut donc ne pas se déclencher. Cela n'a pas été mesuré sur un Mac. La liste de +complétion et les abréviations ne dépendent pas de `Alt` et ne sont pas concernées. diff --git a/docs/guide/labels-en.md b/docs/guide/labels-en.md new file mode 100644 index 00000000..1983b2b3 --- /dev/null +++ b/docs/guide/labels-en.md @@ -0,0 +1,165 @@ +# Labels and decorations + +**Languages:** English (this file) | [Français](labels-fr.md) + +Every label the extension ships, what it means, and what makes a comment blocking. A +repository can change this list ([configuration](configuration-en.md#labels)); what follows +is what you get with no configuration at all. + +## Labels that raise a point + +These are the labels of [Conventional Comments](https://conventionalcomments.org/). They open +a point; they are first the reviewer's. + +| Label | Use it to… | Example | Blocking by default | Can be made blocking | +|---|---|---|:---:|:---:| +| 👏 `praise` | Point out something remarkable in the code. | `praise: very readable error handling` | No | Yes | +| 🔍 `nitpick` | Flag a minor preference, with nothing at stake. | `nitpick: trailing comma` | No | **No** | +| 💡 `suggestion` | Propose an improvement and say why. | `suggestion (non-blocking): extract a method` | No | Yes | +| 🔨 `issue` | Flag a problem to fix, ideally with a lead. | `issue: memory leak in the handler` | **Yes** | — | +| 📌 `todo` | Ask for a small but necessary change. | `todo: rename the variable` | **Yes** | — | +| ❓ `question` | Ask for clarification before concluding. | `question (non-blocking): why this choice?` | No | Yes | +| 💭 `thought` | Share an idea, asking for nothing. | `thought: we could factor this out later` | No | **No** | +| 🧹 `chore` | Ask for a side task before merging (job, doc, config…). | `chore: re-run the coverage job` | **Yes** | — | +| 📝 `note` | Share information everyone should know. | `note: this module is being reworked in Q3` | No | **No** | +| 🔤 `typo` | Flag a typo. | `typo: "recieve" → "receive"` | No | Yes | +| ✨ `polish` | Propose a finishing touch, without changing the meaning. | `polish: align the imports` | No | Yes | +| 🪶 `quibble` | Flag a debatable detail. **Shipped disabled.** | `quibble: slightly long name` | No | Yes | + +`quibble` is the one label shipped disabled: Conventional Comments defines it as a `nitpick` +under another name, and two buttons for one meaning only leave an arbitrary choice. A +repository that wants it enables it with `{ "id": "quibble", "enabled": true }`. + +"Use at least one `praise` per review" is good practice, not a rule: the extension never +checks it. + +## Labels that are not part of Conventional Comments + +Conventional Comments gives review **feedback** a vocabulary and says nothing about +**replying** to it, and it invites teams to diverge from its list. The extension adds seven +labels of its own. They are ordinary labels: same format, same decorations, same rules. None +of them can open a blocking thread. + +### Replying to a point + +| Label | Use it to… | Example | Also accepted | +|---|---|---|---| +| 🤝 `thanks` | Say thank you, without taking a position on the point or the code. | `thanks: thanks for the careful review` | `thx` | +| ✅ `done` | Say the code changed because of the remark. | `done: removed the platform-specific token` | `fixed` | +| 👌 `ack` | Accept a point without changing the code at this stage. | `ack: understood, I'll keep it in mind for the next module` | `acknowledged` | +| ✋ `disagree` | Decline a remark and say why. An opinion: it carries no authority and resolves nothing. | `disagree: the mapping is intentionally platform-independent` | | +| ⚖️ `decision` | Record, with a reason, that a point will **not** be addressed. Written by those who carry the pull request, in the thread it closes. | `decision: out of scope, debt tracked in PROJ-142` | | + +```text +issue (blocking): platform CSS tokens leak into the shared stylesheet +``` +```text +done: removed the platform-specific token +``` + +**`done`, `ack` or `disagree`?** A reply takes a position on one question: did the code +change, and if not, do I concede the point? + +- The code changed → `done`. +- The code did not change and the point was valid (cost, scope, priority, or simply "noted") + → `ack`. +- The code did not change because you contest the point → `disagree`. + +`ack` is not a polite refusal: `ack: right, but I'm leaving it as is` is a `disagree`. + +**`disagree` is not `decision`.** `disagree` is an opinion anyone can voice. `decision` +records a choice of those who carry the pull request; its subject must give the reason in at +least 20 characters, and it is validated even where replies are not +([closing a thread without making the change](writing-comments-en.md#closing-a-blocking-thread-without-making-the-change)). +Neither resolves the thread: that stays a gesture of the platform. + +### Saying where a review stands + +| Label | Use it to… | Example | +|---|---|---| +| 📋 `summary` | Recap a review or one pass: what was checked, what is still open. Closes nothing. | `summary: two points checked, one still open` | +| 🎉 `reviewed` | Close your own review: your points are dealt with, you have nothing to add. Approves nothing. | `reviewed: fixes checked, nothing to add` | + +**When to post `reviewed`.** It closes your review as a whole, not one reading pass. Post it +once each of your points is dealt with (fixed and checked, or set aside by a reply you +accept) and a last read turns up nothing new. Any later change to the pull request reopens +your review. Each reviewer closes their own. What the pull request needs to be merged +(approvals, required reviewers) stays with the platform: the extension does not count +`reviewed`, and no number of them amounts to an approval. + +A `summary` never stands in for `reviewed`, even when no point is left open. + +### Sticking to Conventional Comments + +Six of these seven labels form the **added labels**: `thanks`, `done`, `ack`, `disagree`, +`summary` and `reviewed`. A team that wants the upstream list only disables them in the +repository's configuration, one entry each. The [settings page](settings-en.md#added-labels) +shows the block and copies it for you: + +```json +{ "labels": [ { "id": "thanks", "enabled": false }, + { "id": "done", "enabled": false }, + { "id": "ack", "enabled": false }, + { "id": "disagree", "enabled": false }, + { "id": "summary", "enabled": false }, + { "id": "reviewed", "enabled": false } ] } +``` + +`decision` is not in that group, so that removing the additions does not switch it off. + +## Decorations + +A decoration sits in parentheses between the label and the colon. Several are separated by +commas. + +| Decoration | Effect | +|---|---| +| `(blocking)` | The comment is blocking, whatever its label. | +| `(non-blocking)` | The comment is not blocking, whatever its label. | +| `(if-minor)` | Not blocking: address the point only if the effort is small. | +| A free decoration: `(security)`, `(perf)`, `(a11y)`… | None. It describes the comment. Allowed by default (`decorations.allowFree`). | + +```text +suggestion (non-blocking, perf): cache the compiled pattern +``` + +A decoration is one word made of letters, digits and hyphens. `(non blocking)`, `()` and +`(blocking,,)` are errors; `(BLOCKING)` and `( blocking )` are accepted with a warning and a +one-click fix. + +`suggestion` and `question` say nothing by themselves about whether the point blocks, so the +extension warns when they carry none of the three decorations above. + +## What makes a comment blocking + +The first rule that applies wins: + +1. A label that can never be blocking (`nitpick`, `thought`, `note` and the seven labels of + the extension) with `(blocking)` is an **error**, `E-CONFLICT`. +2. `(blocking)` together with `(non-blocking)` or `(if-minor)` is an **error**, `E-CONFLICT`. +3. `(blocking)` alone → blocking. +4. `(non-blocking)` or `(if-minor)` → not blocking. +5. No such decoration → the label decides: `issue`, `todo` and `chore` are blocking, the + others are not. + +| Comment | Blocking? | +|---|---| +| `issue: …` | Yes | +| `issue (non-blocking): …` | No | +| `issue (if-minor): …` | No | +| `suggestion: …` | No, with a warning asking for a decoration | +| `suggestion (blocking): …` | Yes | +| `nitpick (blocking): …` | Error | + +A blocking comment opens a **blocking thread** when it is the first comment of a thread that +can be resolved. The banner counts those threads while they are unresolved +([the banner](writing-comments-en.md#once-comments-are-published)). Editing `issue:` into +`note:` makes the thread non-blocking: the extension reads the current state of the page and +keeps no history. + +## Aliases + +An alias is another spelling accepted for a label: `fixed:` is read as `done:`, `thx:` as +`thanks:`, `acknowledged:` as `ack:`. An alias produces no diagnostic; the extension offers +to rewrite it to the label's name, without insisting. A repository can declare its own, for +example `bug` for `issue` ([configuration](configuration-en.md#labels)). diff --git a/docs/guide/labels-fr.md b/docs/guide/labels-fr.md new file mode 100644 index 00000000..b70c2a99 --- /dev/null +++ b/docs/guide/labels-fr.md @@ -0,0 +1,166 @@ +# Labels et décorations + +**Langues :** [English](labels-en.md) | Français (ce fichier) + +Tous les labels livrés avec l'extension, ce qu'ils veulent dire, et ce qui rend un commentaire +bloquant. Un dépôt peut modifier cette liste ([configuration](configuration-fr.md#labels)) ; +ce qui suit est ce que vous obtenez sans aucune configuration. + +## Les labels qui soulèvent un point + +Ce sont les labels de [Conventional Comments](https://conventionalcomments.org/). Ils ouvrent +un point ; ils sont d'abord ceux du relecteur. + +| Label | À utiliser pour… | Exemple | Bloquant par défaut | Peut devenir bloquant | +|---|---|---|:---:|:---:| +| 👏 `praise` | Saluer un point remarquable du code. | `praise: gestion d’erreur très lisible` | Non | Oui | +| 🔍 `nitpick` | Signaler une préférence mineure, sans enjeu. | `nitpick: virgule finale` | Non | **Non** | +| 💡 `suggestion` | Proposer une amélioration et dire pourquoi. | `suggestion (non-blocking): extraire une méthode` | Non | Oui | +| 🔨 `issue` | Signaler un problème à corriger, idéalement avec une piste. | `issue: fuite mémoire sur le handler` | **Oui** | — | +| 📌 `todo` | Demander un petit changement nécessaire. | `todo: renommer la variable` | **Oui** | — | +| ❓ `question` | Demander une précision avant de conclure. | `question (non-blocking): pourquoi ce choix ?` | Non | Oui | +| 💭 `thought` | Partager une idée, sans rien demander. | `thought: on pourrait factoriser plus tard` | Non | **Non** | +| 🧹 `chore` | Demander une tâche annexe avant la fusion (job, doc, config…). | `chore: relancer le job de couverture` | **Oui** | — | +| 📝 `note` | Porter une information à la connaissance de tous. | `note: ce module part en refonte au T3` | Non | **Non** | +| 🔤 `typo` | Signaler une faute de frappe. | `typo: « recieve » → « receive »` | Non | Oui | +| ✨ `polish` | Proposer une finition, sans changer le sens. | `polish: aligner les imports` | Non | Oui | +| 🪶 `quibble` | Signaler un détail discutable. **Livré désactivé.** | `quibble: nom un peu long` | Non | Oui | + +`quibble` est le seul label livré désactivé : Conventional Comments le définit comme un +`nitpick` sous un autre nom, et deux boutons pour un même sens ne laissent qu'un choix +arbitraire. Un dépôt qui le veut l'active avec `{ "id": "quibble", "enabled": true }`. + +« Utiliser au moins un `praise` par revue » est une bonne pratique, pas une règle : +l'extension ne le vérifie jamais. + +## Les labels qui ne font pas partie de Conventional Comments + +Conventional Comments donne un vocabulaire à la **remarque** de revue et ne dit rien de la +**réponse** à cette remarque, et il invite les équipes à s'écarter de sa liste. L'extension +ajoute sept labels qui lui sont propres. Ce sont des labels ordinaires : même format, mêmes +décorations, mêmes règles. Aucun d'eux ne peut ouvrir un fil bloquant. + +### Répondre à un point + +| Label | À utiliser pour… | Exemple | Aussi accepté | +|---|---|---|---| +| 🤝 `thanks` | Remercier, sans prendre position sur le point ni sur le code. | `thanks: merci pour la relecture attentive` | `thx` | +| ✅ `done` | Indiquer que le code a changé à la suite de la remarque. | `done: jeton propre à la plateforme retiré` | `fixed` | +| 👌 `ack` | Accepter un point sans changer le code à ce stade. | `ack: bien noté, je garde ça pour le module suivant` | `acknowledged` | +| ✋ `disagree` | Décliner une remarque en disant pourquoi. Un avis : il n'emporte aucune autorité et ne résout rien. | `disagree: la correspondance est volontairement indépendante de la plateforme` | | +| ⚖️ `decision` | Acter, motif à l'appui, qu'un point ne sera **pas** traité. Écrit par ceux qui portent la PR, dans le fil qu'il clôt. | `decision: hors périmètre, dette suivie en PROJ-142` | | + +```text +issue (blocking): les jetons CSS d'une plateforme fuient dans la feuille partagée +``` +```text +done: jeton propre à la plateforme retiré +``` + +**`done`, `ack` ou `disagree` ?** Une réponse prend position sur une seule question : le code +a-t-il changé, et si non, est-ce que je concède le point ? + +- Le code a changé → `done`. +- Le code n'a pas changé et le point était valide (coût, périmètre, priorité, ou simplement + « bien noté ») → `ack`. +- Le code n'a pas changé parce que vous contestez le point → `disagree`. + +`ack` n'est pas un refus poli : `ack: juste, mais je laisse tel quel` est un `disagree`. + +**`disagree` n'est pas `decision`.** `disagree` est un avis, que n'importe qui peut exprimer. +`decision` acte un choix de ceux qui portent la PR ; son sujet doit donner le motif en au +moins 20 caractères, et il est validé même là où les réponses ne le sont pas +([clore un fil sans faire le changement](writing-comments-fr.md#clore-un-fil-bloquant-sans-faire-le-changement-demandé)). +Ni l'un ni l'autre ne résout le fil : cela reste un geste de la plateforme. + +### Dire où en est une revue + +| Label | À utiliser pour… | Exemple | +|---|---|---| +| 📋 `summary` | Faire le point sur une revue ou sur une passe : ce qui a été vérifié, ce qui reste ouvert. Ne clôt rien. | `summary: deux points vérifiés, un reste ouvert` | +| 🎉 `reviewed` | Clore votre propre revue : vos points sont traités, vous n'avez rien à ajouter. N'approuve rien. | `reviewed: corrections vérifiées, rien à ajouter` | + +**Quand publier `reviewed`.** Il clôt votre revue dans son ensemble, pas une passe de lecture. +Publiez-le quand chacun de vos points est traité (corrigé et vérifié, ou écarté par une +réponse que vous acceptez) et qu'une dernière lecture ne fait rien apparaître de nouveau. +Toute modification ultérieure de la pull request rouvre votre revue. Chaque relecteur clôt la +sienne. Ce qu'il faut à la pull request pour être fusionnée (approbations, relecteurs requis) +reste l'affaire de la plateforme : l'extension ne compte pas les `reviewed`, et aucun nombre +de `reviewed` ne vaut approbation. + +Un `summary` ne tient jamais lieu de `reviewed`, même quand plus aucun point n'est ouvert. + +### S'en tenir à Conventional Comments + +Six de ces sept labels forment les **labels ajoutés** : `thanks`, `done`, `ack`, `disagree`, +`summary` et `reviewed`. Une équipe qui ne veut que la liste de l'amont les désactive dans la +configuration du dépôt, une entrée par label. La +[page de réglages](settings-fr.md#labels-ajoutés) affiche le bloc et le copie pour vous : + +```json +{ "labels": [ { "id": "thanks", "enabled": false }, + { "id": "done", "enabled": false }, + { "id": "ack", "enabled": false }, + { "id": "disagree", "enabled": false }, + { "id": "summary", "enabled": false }, + { "id": "reviewed", "enabled": false } ] } +``` + +`decision` ne fait pas partie de ce groupe, pour que retirer les ajouts ne le désactive pas. + +## Décorations + +Une décoration se place entre parenthèses, entre le label et le deux-points. Plusieurs +décorations se séparent par des virgules. + +| Décoration | Effet | +|---|---| +| `(blocking)` | Le commentaire est bloquant, quel que soit son label. | +| `(non-blocking)` | Le commentaire n'est pas bloquant, quel que soit son label. | +| `(if-minor)` | Non bloquant : ne traiter le point que si l'effort est faible. | +| Une décoration libre : `(security)`, `(perf)`, `(a11y)`… | Aucun. Elle décrit le commentaire. Autorisée par défaut (`decorations.allowFree`). | + +```text +suggestion (non-blocking, perf): mettre en cache le motif compilé +``` + +Une décoration est un mot fait de lettres, de chiffres et de traits d'union. `(non blocking)`, +`()` et `(blocking,,)` sont des erreurs ; `(BLOCKING)` et `( blocking )` sont acceptés avec +un avertissement et une correction en un clic. + +`suggestion` et `question` ne disent rien par eux-mêmes du caractère bloquant du point : +l'extension avertit donc quand ils ne portent aucune des trois décorations ci-dessus. + +## Ce qui rend un commentaire bloquant + +La première règle qui s'applique l'emporte : + +1. Un label qui ne peut jamais être bloquant (`nitpick`, `thought`, `note` et les sept labels + de l'extension) avec `(blocking)` est une **erreur**, `E-CONFLICT`. +2. `(blocking)` avec `(non-blocking)` ou `(if-minor)` est une **erreur**, `E-CONFLICT`. +3. `(blocking)` seul → bloquant. +4. `(non-blocking)` ou `(if-minor)` → non bloquant. +5. Aucune de ces décorations → le label décide : `issue`, `todo` et `chore` sont bloquants, + les autres ne le sont pas. + +| Commentaire | Bloquant ? | +|---|---| +| `issue: …` | Oui | +| `issue (non-blocking): …` | Non | +| `issue (if-minor): …` | Non | +| `suggestion: …` | Non, avec un avertissement qui demande une décoration | +| `suggestion (blocking): …` | Oui | +| `nitpick (blocking): …` | Erreur | + +Un commentaire bloquant ouvre un **fil bloquant** quand il est le premier commentaire d'un +fil qui peut être résolu. Le bandeau compte ces fils tant qu'ils ne sont pas résolus +([le bandeau](writing-comments-fr.md#une-fois-les-commentaires-publiés)). Éditer `issue:` en +`note:` rend le fil non bloquant : l'extension lit l'état courant de la page et ne garde +aucun historique. + +## Alias + +Un alias est une autre graphie acceptée pour un label : `fixed:` est lu comme `done:`, `thx:` +comme `thanks:`, `acknowledged:` comme `ack:`. Un alias ne produit aucun diagnostic ; +l'extension propose de le réécrire avec le nom du label, sans insister. Un dépôt peut déclarer +les siens, par exemple `bug` pour `issue` ([configuration](configuration-fr.md#labels)). diff --git a/docs/guide/modes-and-adoption-en.md b/docs/guide/modes-and-adoption-en.md new file mode 100644 index 00000000..6692cb75 --- /dev/null +++ b/docs/guide/modes-and-adoption-en.md @@ -0,0 +1,96 @@ +# Modes and adoption + +**Languages:** English (this file) | [Français](modes-and-adoption-fr.md) + +How far the extension goes, from silent to blocking, and how a team gets there without +breaking its workflow. + +## The three modes + +| Mode | Toolbar and keyboard input | Diagnostics shown | Send blocked | +|---|:---:|:---:|:---:| +| `off` | No | No | No | +| `assist` (default) | Yes | Yes | No | +| `enforce` | Yes | Yes | Yes, for a comment with an error | + +A repository sets its mode in [its configuration file](configuration-en.md#mode); an +organisation can set a default for all its repositories and a minimum none of them can go +below ([deploying for an organisation](organization-en.md)). Nobody sets the mode from the +extension's settings page. + +`warn` no longer exists. A configuration that still says `"mode": "warn"` is read as +`"assist"`, with a notice asking to update it. + +## What `enforce` does + +When a comment has at least one **error**, the send button is greyed out and its activation +is intercepted, with the mouse and with the keyboard (`Ctrl+Enter`, `Cmd+Enter`). The reason +is announced to screen readers, and the button stays reachable with `Tab`. Warnings never +block. + +Blocking needs two conditions: + +1. the effective mode is `enforce`; +2. the extension could **read** the configuration. If it could not, it shows *Configuration + unread* and behaves as in `assist`: a send is never refused in the name of a rule that + could not be read. + +Before it blocks, the extension re-reads the configuration, bypassing its cache. If the +re-read configuration no longer blocks the comment, the button is released and a message +invites you to send again. + +## What `enforce` does not do + +**The extension is a guard rail, not a wall.** It runs in the browser where it is installed. +A comment posted through the platform's API, a command-line tool, an IDE, another browser or +a machine without the extension is not checked. Nothing in the product controls that +downstream. + +**It does not control the merge.** Unresolved blocking threads are *reported* by the banner, +never prevented from merging +([DEC0010](../idr/DEC0010-the-extension-is-the-whole-product-en.md)). A team that wants +merges gated on resolved conversations uses its platform's own settings, such as required +conversation resolution. + +**There is no bypass button**, and that is deliberate. Such a button would control nothing, +since the extension can be disabled in two clicks, and it would move the justification out of +the review. When a blocking point will not be addressed, say so in the thread with a +[`decision`](writing-comments-en.md#closing-a-blocking-thread-without-making-the-change): +readable by everyone, where the discussion took place, kept with the pull request. + +## Recommended path + +```text +assist → enforce on a pilot repository → rollout +``` + +1. **Start in `assist`**, the default. People get the toolbar, the pill and the badges; + nothing is refused. +2. **Settle the rules while still in `assist`.** Adjust labels, severities, exemptions for + bots and commands. A change applies at once to open pull requests, so this is the moment to + see what the pill and the banner report. +3. **Switch one pilot repository to `enforce`**, with `{ "mode": "enforce" }` in its file. +4. **Roll out**, repository by repository or through the organisation's configuration. + +Before the switch, check the cases that would otherwise surprise people: + +- commands addressed to bots (`@dependabot rebase`, `/retest`) need `toolCommands`, or they + are refused like any comment without a label; +- accounts that comment automatically need `exemptUsers`; +- on GitLab, the send guard does not apply yet, and people using GitLab's rich text editor + get no assistance at all ([platforms](platforms-en.md)). + +## Rolling back + +Relaxing the mode lifts the blocking at the next send attempt, with no cache to wait for. +The order matters, because a lower level cannot relax what a higher one imposes: + +1. the enterprise floor, if it imposes `enforce`; +2. the organisation's configuration, which covers every repository that does not write its + own `mode`; +3. each repository that writes `"mode": "enforce"` in its own file. List them before the + switch, not during the incident. + +To check: on a test pull request, send a comment without a label. It must go out. + +The operating procedures in full, in French: [`operations-fr.md`](../operations-fr.md). diff --git a/docs/guide/modes-and-adoption-fr.md b/docs/guide/modes-and-adoption-fr.md new file mode 100644 index 00000000..7d8994dd --- /dev/null +++ b/docs/guide/modes-and-adoption-fr.md @@ -0,0 +1,99 @@ +# Modes et adoption + +**Langues :** [English](modes-and-adoption-en.md) | Français (ce fichier) + +Jusqu'où va l'extension, de silencieuse à bloquante, et comment une équipe y arrive sans +casser sa façon de travailler. + +## Les trois modes + +| Mode | Barre d'outils et saisie au clavier | Diagnostics affichés | Envoi bloqué | +|---|:---:|:---:|:---:| +| `off` | Non | Non | Non | +| `assist` (par défaut) | Oui | Oui | Non | +| `enforce` | Oui | Oui | Oui, pour un commentaire en erreur | + +Un dépôt fixe son mode dans [son fichier de configuration](configuration-fr.md#mode) ; une +organisation peut fixer une valeur par défaut pour tous ses dépôts et un minimum sous lequel +aucun ne peut descendre ([déployer pour une organisation](organization-fr.md)). Personne ne +fixe le mode depuis la page de réglages de l'extension. + +`warn` n'existe plus. Une configuration qui écrit encore `"mode": "warn"` est lue comme +`"assist"`, avec un avis qui demande de la mettre à jour. + +## Ce que fait `enforce` + +Quand un commentaire a au moins une **erreur**, le bouton d'envoi est grisé et son activation +est interceptée, à la souris comme au clavier (`Ctrl+Entrée`, `Cmd+Entrée`). Le motif est +annoncé aux lecteurs d'écran, et le bouton reste atteignable avec `Tab`. Les avertissements ne +bloquent jamais. + +Le blocage demande deux conditions : + +1. le mode effectif est `enforce` ; +2. l'extension a pu **lire** la configuration. Si elle n'a pas pu, elle affiche *Configuration + non lue* et se comporte comme en `assist` : un envoi n'est jamais refusé au nom d'une règle + qui n'a pas pu être lue. + +Avant de bloquer, l'extension relit la configuration, sans passer par son cache. Si la +configuration relue ne bloque plus le commentaire, le bouton est libéré et un message vous +invite à renvoyer le commentaire. + +## Ce que `enforce` ne fait pas + +**L'extension est un garde-fou, pas un mur.** Elle s'exécute dans le navigateur où elle est +installée. Un commentaire publié par l'API de la plateforme, un outil en ligne de commande, un +IDE, un autre navigateur ou une machine sans l'extension n'est pas contrôlé. Rien dans le +produit ne contrôle cela en aval. + +**Elle ne contrôle pas la fusion.** Les fils bloquants non résolus sont *signalés* par le +bandeau, jamais empêchés de fusionner +([DEC0010](../idr/DEC0010-the-extension-is-the-whole-product-fr.md)). Une équipe qui veut +conditionner les fusions à la résolution des conversations utilise les réglages de sa +plateforme, comme la résolution obligatoire des conversations. + +**Il n'y a pas de bouton de contournement**, et c'est voulu. Un tel bouton ne contrôlerait +rien, puisque l'extension se désactive en deux clics, et il sortirait la justification de la +revue. Quand un point bloquant ne sera pas traité, dites-le dans le fil avec une +[`decision`](writing-comments-fr.md#clore-un-fil-bloquant-sans-faire-le-changement-demandé) : +lisible par tous, à l'endroit où la discussion a eu lieu, conservée avec la pull request. + +## Trajectoire recommandée + +```text +assist → enforce sur un dépôt pilote → généralisation +``` + +1. **Commencez en `assist`**, le mode par défaut. Chacun dispose de la barre d'outils, de la + pastille et des badges ; rien n'est refusé. +2. **Arrêtez les règles tant que vous êtes en `assist`.** Ajustez les labels, les sévérités, + les exemptions pour les bots et les commandes. Un changement s'applique aussitôt aux pull + requests ouvertes : c'est le moment de voir ce que signalent la pastille et le bandeau. +3. **Passez un dépôt pilote en `enforce`**, avec `{ "mode": "enforce" }` dans son fichier. +4. **Généralisez**, dépôt par dépôt ou par la configuration d'organisation. + +Avant la bascule, vérifiez les cas qui, sinon, surprendraient : + +- les commandes adressées aux bots (`@dependabot rebase`, `/retest`) ont besoin de + `toolCommands`, sans quoi elles sont refusées comme n'importe quel commentaire sans label ; +- les comptes qui commentent automatiquement ont besoin de `exemptUsers` ; +- sur GitLab, le blocage de l'envoi ne s'applique pas encore, et les personnes qui utilisent + l'éditeur de texte enrichi de GitLab ne reçoivent aucune assistance + ([plateformes](platforms-fr.md)). + +## Retour arrière + +Assouplir le mode lève le blocage à la tentative d'envoi suivante, sans cache à attendre. +L'ordre compte, car un niveau inférieur ne peut pas assouplir ce qu'un niveau supérieur +impose : + +1. le plancher d'entreprise, s'il impose `enforce` ; +2. la configuration d'organisation, qui couvre tous les dépôts qui n'écrivent pas leur propre + `mode` ; +3. chaque dépôt qui écrit `"mode": "enforce"` dans son propre fichier. Listez-les avant la + bascule, pas pendant l'incident. + +Pour vérifier : sur une pull request de test, envoyez un commentaire sans label. Il doit +partir. + +Les procédures d'exploitation complètes : [`operations-fr.md`](../operations-fr.md). diff --git a/docs/guide/organization-en.md b/docs/guide/organization-en.md new file mode 100644 index 00000000..89b44154 --- /dev/null +++ b/docs/guide/organization-en.md @@ -0,0 +1,128 @@ +# Deploying for an organisation + +**Languages:** English (this file) | [Français](organization-fr.md) + +What an administrator can set for every workstation: a configuration shared by all +repositories, a floor no repository can go below, the hosts the extension serves, and +telemetry. Everything on this page is optional; a team can use the extension with a +repository file alone, or with nothing. + +## The channel: the browser's enterprise policy + +The extension reads a managed policy through the browser (`chrome.storage.managed`, the +`3rdparty` policy node on Chromium browsers). Its scope is the workstation. The policy has +three top-level keys: + +```json +{ + "floor": { + "floorVersion": 1, + "configUrl": "https://intranet.example/cc/organisation.json", + "minimumMode": "assist" + }, + "allowedHosts": [ + { "host": "ghes.example.corp", "platform": "github" }, + { "host": "intranet.example", "platform": "config" } + ], + "telemetry": { "enabled": false, "endpoint": "https://metrics.example/cc" } +} +``` + +Without a policy, nothing is imposed: repositories and product defaults decide alone. + +## The organisation's configuration + +`floor.configUrl` is the address of a JSON document with the +[same keys as a repository file](configuration-en.md#keys). It sits between the repository +file and the product defaults: it sets the default for every repository that does not write +the key itself. + +- The address **only** comes from the policy. A `configUrl` written in a repository file is + ignored and reported. +- The extension needs access to the host that serves it. Declare that host in `allowedHosts` + with `"platform": "config"` when it is not a platform domain. +- A repository file wins over this document. To impose a value, use the floor. + +## The floor + +The floor bounds what the levels below may write. It is not a configuration: it sets no +default, and a key left out is not bounded. + +```json +{ + "floor": { + "floorVersion": 1, + "configUrl": "https://intranet.example/cc/organisation.json", + "minimumMode": "enforce", + "severities": { "E-NO-LABEL": "error", "E-UNKNOWN-LABEL": "error" }, + "labels": { "minimum": ["issue", "todo"] }, + "rules": { "minDecisionSubjectLength": 20 }, + "exemptUsers": { "minimum": ["build-service"], "closed": false }, + "allowlistPatterns": { "minimum": [], "closed": true }, + "toolCommands": { "minimum": [], "closed": false }, + "configCacheTtlSeconds": 3600 + } +} +``` + +| Key | What a level below can no longer do | +|---|---| +| `minimumMode` | Set a mode below it. The scale is `off` < `assist` < `enforce`. | +| `severities` | Lower the severity of the listed codes. | +| `labels.minimum` | Disable these labels, make them non-blocking by default, or forbid `(blocking)` on them. | +| `rules.minDecisionSubjectLength` | Accept a shorter reason for a `decision`. | +| `exemptUsers`, `allowlistPatterns`, `toolCommands` | Remove an entry of `minimum`. With `closed: true`, add any entry at all. | +| `configCacheTtlSeconds` | Keep a configuration in cache **longer** than this. | + +Tightening is always allowed below the floor; relaxing is not. A repository that writes +`{"mode": "off"}` under a floor at `enforce` keeps `enforce`, and everyone sees a notice +saying the key was ignored. + +`labels.minimum` matters more than it looks: without it, a repository can disable `issue`, +`todo` and `chore`, after which no thread is blocking any more. + +A floor whose `floorVersion` is newer than the extension supports is never dropped +silently: the extension falls back on `assist`, or on the floor it knew before if that one was +stricter, and reports it. + +## The hosts + +`allowedHosts` tells the extension which platform serves each host of yours, so that nobody +has to classify it by hand in the settings page: + +| `platform` | For | +|---|---| +| `"github"` | GitHub Enterprise Server, a `ghe.com` subdomain | +| `"azdo"` | Azure DevOps Server | +| `"gitlab"` | GitLab Self-Managed | +| `"config"` | A host that only serves the organisation's configuration | + +Each entry must name its platform; an entry without one activates nothing. A subdomain +wildcard is accepted in `host` (`*.ghe.com`). + +Site access itself, the permission each person otherwise grants from the settings page, is a +matter for your browser's extension-management policy. A host the policy classifies is shown +as such in the settings page, marked *enterprise policy*. + +## Telemetry + +Off by default. It turns on only when **both** hold: the policy declares +`"enabled": true` with an `https:` `endpoint`, **and** the person ticks the box in their +settings page. A repository can neither enable it nor choose the destination. + +It sends aggregate counters: a label inserted through the extension and its kind, a +diagnostic code shown, a selector that found nothing, with the mode and the repository. Never +the text of a comment, of code or of a diff, nor the address of the page. + +These counters do not yet allow a compliance rate to be computed: no event counts comments +written or sent. The full list of what is collected is in the +[privacy policy](../../PRIVACY.md). + +## Installing the extension on every workstation + +Browsers can force the installation of an extension by policy: `ExtensionInstallForcelist` on +Chrome and Edge, `ExtensionSettings` with `"installation_mode": "force_installed"` on +Firefox. Both install from a store or from an update server of your own, which is also what +gives automatic updates. The archives of the +[releases page](https://github.com/reefact/conventional-comments-toolkit/releases) are meant +for trying the extension: loaded by hand, they never update. diff --git a/docs/guide/organization-fr.md b/docs/guide/organization-fr.md new file mode 100644 index 00000000..fac251f4 --- /dev/null +++ b/docs/guide/organization-fr.md @@ -0,0 +1,132 @@ +# Déployer pour une organisation + +**Langues :** [English](organization-en.md) | Français (ce fichier) + +Ce qu'un administrateur peut fixer pour tous les postes de travail : une configuration commune +à tous les dépôts, un plancher sous lequel aucun dépôt ne peut descendre, les hôtes que +l'extension sert, et la télémétrie. Tout ce que décrit cette page est facultatif ; une équipe +peut utiliser l'extension avec un fichier de dépôt seul, ou sans rien. + +## Le canal : la politique d'entreprise du navigateur + +L'extension lit une politique gérée par l'intermédiaire du navigateur +(`chrome.storage.managed`, le nœud de politique `3rdparty` sur les navigateurs Chromium). Sa +portée est le poste de travail. La politique a trois clés de premier niveau : + +```json +{ + "floor": { + "floorVersion": 1, + "configUrl": "https://intranet.example/cc/organisation.json", + "minimumMode": "assist" + }, + "allowedHosts": [ + { "host": "ghes.example.corp", "platform": "github" }, + { "host": "intranet.example", "platform": "config" } + ], + "telemetry": { "enabled": false, "endpoint": "https://metrics.example/cc" } +} +``` + +Sans politique, rien n'est imposé : les dépôts et les valeurs par défaut du produit décident +seuls. + +## La configuration d'organisation + +`floor.configUrl` est l'adresse d'un document JSON qui porte les +[mêmes clés qu'un fichier de dépôt](configuration-fr.md#clés). Il se place entre le fichier +du dépôt et les valeurs par défaut du produit : il fixe la valeur par défaut pour tout dépôt +qui n'écrit pas lui-même la clé. + +- L'adresse ne vient **que** de la politique. Une `configUrl` écrite dans un fichier de dépôt + est ignorée et signalée. +- L'extension a besoin d'accéder à l'hôte qui le sert. Déclarez cet hôte dans `allowedHosts` + avec `"platform": "config"` quand ce n'est pas un domaine de plateforme. +- Un fichier de dépôt l'emporte sur ce document. Pour imposer une valeur, utilisez le + plancher. + +## Le plancher + +Le plancher borne ce que les niveaux inférieurs peuvent écrire. Ce n'est pas une +configuration : il ne fixe aucune valeur par défaut, et une clé omise n'est pas bornée. + +```json +{ + "floor": { + "floorVersion": 1, + "configUrl": "https://intranet.example/cc/organisation.json", + "minimumMode": "enforce", + "severities": { "E-NO-LABEL": "error", "E-UNKNOWN-LABEL": "error" }, + "labels": { "minimum": ["issue", "todo"] }, + "rules": { "minDecisionSubjectLength": 20 }, + "exemptUsers": { "minimum": ["build-service"], "closed": false }, + "allowlistPatterns": { "minimum": [], "closed": true }, + "toolCommands": { "minimum": [], "closed": false }, + "configCacheTtlSeconds": 3600 + } +} +``` + +| Clé | Ce qu'un niveau inférieur ne peut plus faire | +|---|---| +| `minimumMode` | Fixer un mode en dessous. L'échelle est `off` < `assist` < `enforce`. | +| `severities` | Abaisser la sévérité des codes listés. | +| `labels.minimum` | Désactiver ces labels, les rendre non bloquants par défaut, ou y interdire `(blocking)`. | +| `rules.minDecisionSubjectLength` | Accepter un motif plus court pour une `decision`. | +| `exemptUsers`, `allowlistPatterns`, `toolCommands` | Retirer une entrée de `minimum`. Avec `closed: true`, ajouter la moindre entrée. | +| `configCacheTtlSeconds` | Garder une configuration en cache **plus longtemps** que cette durée. | + +Durcir est toujours permis sous le plancher ; assouplir ne l'est pas. Un dépôt qui écrit +`{"mode": "off"}` sous un plancher à `enforce` garde `enforce`, et tout le monde voit un avis +indiquant que la clé a été ignorée. + +`labels.minimum` compte plus qu'il n'y paraît : sans lui, un dépôt peut désactiver `issue`, +`todo` et `chore`, après quoi plus aucun fil n'est bloquant. + +Un plancher dont la `floorVersion` est plus récente que ce que l'extension prend en charge +n'est jamais abandonné en silence : l'extension se replie sur `assist`, ou sur le plancher +qu'elle connaissait auparavant si celui-ci était plus strict, et le signale. + +## Les hôtes + +`allowedHosts` indique à l'extension quelle plateforme sert chacun de vos hôtes, pour que +personne n'ait à le classer à la main dans la page de réglages : + +| `platform` | Pour | +|---|---| +| `"github"` | GitHub Enterprise Server, un sous-domaine de `ghe.com` | +| `"azdo"` | Azure DevOps Server | +| `"gitlab"` | GitLab Self-Managed | +| `"config"` | Un hôte qui ne sert que la configuration d'organisation | + +Chaque entrée doit nommer sa plateforme ; une entrée qui n'en nomme pas n'active rien. Un +joker de sous-domaine est accepté dans `host` (`*.ghe.com`). + +L'accès aux sites lui-même, la permission que chaque personne accorde sinon depuis la page de +réglages, relève de la politique de gestion des extensions de votre navigateur. Un hôte que la +politique classe est affiché comme tel dans la page de réglages, avec la mention *politique +d’entreprise*. + +## Télémétrie + +Désactivée par défaut. Elle ne s'active que si **les deux** conditions sont réunies : la +politique déclare `"enabled": true` avec un `endpoint` en `https:`, **et** la personne coche +la case dans sa page de réglages. Un dépôt ne peut ni l'activer ni en choisir la destination. + +Elle envoie des compteurs agrégés : un label inséré par l'extension et son type, un code de +diagnostic affiché, un sélecteur qui n'a rien trouvé, avec le mode et le dépôt. Jamais le +texte d'un commentaire, de code ou d'un diff, ni l'adresse de la page. + +Ces compteurs ne permettent pas encore de calculer un taux de conformité : aucun événement ne +compte les commentaires écrits ou envoyés. La liste complète de ce qui est collecté figure +dans la [politique de confidentialité](../../PRIVACY.md). + +## Installer l'extension sur tous les postes de travail + +Les navigateurs peuvent forcer l'installation d'une extension par politique : +`ExtensionInstallForcelist` sur Chrome et Edge, `ExtensionSettings` avec +`"installation_mode": "force_installed"` sur Firefox. Les deux installent depuis un store ou +depuis un serveur de mise à jour à vous, et c'est aussi ce qui apporte les mises à jour +automatiques. Les archives de la +[page des releases](https://github.com/reefact/conventional-comments-toolkit/releases) sont +faites pour essayer l'extension : chargées à la main, elles ne se mettent jamais à jour. diff --git a/docs/guide/platforms-en.md b/docs/guide/platforms-en.md new file mode 100644 index 00000000..87dcd291 --- /dev/null +++ b/docs/guide/platforms-en.md @@ -0,0 +1,85 @@ +# Platforms + +**Languages:** English (this file) | [Français](platforms-fr.md) + +What the extension does on each platform, and what it does not do yet. One extension carries +the three adapters; each is active only on the domains you allowed. + +## At a glance + +| | GitHub | Azure DevOps | GitLab | +|---|:---:|:---:|:---:| +| Toolbar, keyboard input, status pill | Yes | Yes | Yes, in the Markdown editor only | +| Badges on published comments | Yes | Yes | Yes | +| Banner of unresolved blocking threads | Yes | Yes | Yes | +| Thread filter | Yes | Yes | Yes, except on the *Changes* tab | +| Reads the repository's `.conventional-comments.json` | Yes | Yes | **Not yet** | +| Send guard (`enforce`) | Yes | Yes | **No** | +| A general comment can open a blocking thread | No | Yes | Yes, when published with *Start thread* | +| Body of a review submitted as a whole | Yes | Does not exist | Yes | +| Suggestion block read as a `suggestion` | Yes | Yes | Not yet | + +## Domains + +| Offer | Domain | In the settings page | +|---|---|---| +| GitHub.com | `github.com` | *Known domains*, one click | +| GitHub Enterprise Cloud with data residency | your own subdomain of `ghe.com` | *Other domains*: type it, choose GitHub | +| GitHub Enterprise Server | your own domain | *Other domains*: type it, choose GitHub | +| Azure DevOps Services | `dev.azure.com` | *Known domains*, one click | +| Azure DevOps Services, legacy URL | `.visualstudio.com` | *Other domains*: type it, choose Azure DevOps | +| Azure DevOps Server | your own domain | *Other domains*: type it, choose Azure DevOps | +| GitLab.com | `gitlab.com` | *Known domains*, one click | +| GitLab Self-Managed, GitLab Dedicated | your own domain | *Other domains*: type it, choose GitLab. **Not measured.** | + +No domain is granted at installation, `github.com` included. You type your own subdomain +rather than allowing all of `ghe.com` or `visualstudio.com`: the extension only gets the one +host you use. + +## GitHub + +- Both pull request pages are supported: the classic *Conversation* page and the newer + *Overview*, and *Files changed*. +- The general conversation of a pull request has no "resolve" button, so a blocking label + written there cannot open a blocking thread. The pill says so with `W-NOT-BLOCKABLE`. +- Submitting a review validates its body (`scope.validateReviewSummary`); approving with no + text stays possible. +- A thread is resolved when the conversation is marked *Resolved*. +- The repository file is read through the page's own session: private repositories work for + anyone signed in with access to them. + +## Azure DevOps + +- Every send button goes through validation: *Comment*, *Reply*, *Reply & resolve*, *Update*, + *Update & resolve*, *Reply & reactivate*. +- A general comment is a thread with a status, like a comment on a line: a blocking label + there counts among the blocking threads. +- A thread counts as unresolved while its status is *Active* or *Pending*, or when it has + none. Any other status counts as resolved. +- There is no review body: `scope.validateReviewSummary` is ignored. +- Pipeline comments are posted by `Project Collection Build Service ()` or + ` Build Service ()`: those are the names to put in `exemptUsers`. + +## GitLab + +Measured on gitlab.com only. + +- **The extension does not read the repository file on GitLab yet.** It applies the product + defaults, shows *Configuration unread*, and therefore **never blocks a send** there, whatever + the mode. +- **Only the Markdown editor is handled.** GitLab lets each person switch to a rich text + editor and remembers the choice. In that editor the extension stays out entirely: no + toolbar, no validation. Switch back with *Switch to plain text editing* under the field. +- A general comment published with *Start thread* is a resolvable thread and can be blocking. + Published with *Comment*, it is a plain note: a blocking label there is not counted, and no + warning says so. +- On the *Changes* tab, the thread filter is not shown, and resolved threads are not in the + page for the extension to read. +- GitLab Self-Managed and GitLab Dedicated have not been measured. + +## Browsers + +| Browser | Version | +|---|---| +| Chrome, Edge, other Chromium browsers | The three latest major versions | +| Firefox | 128 or later | diff --git a/docs/guide/platforms-fr.md b/docs/guide/platforms-fr.md new file mode 100644 index 00000000..8306aa0c --- /dev/null +++ b/docs/guide/platforms-fr.md @@ -0,0 +1,88 @@ +# Plateformes + +**Langues :** [English](platforms-en.md) | Français (ce fichier) + +Ce que fait l'extension sur chaque plateforme, et ce qu'elle ne fait pas encore. Une seule +extension porte les trois adaptateurs ; chacun n'est actif que sur les domaines que vous avez +autorisés. + +## En un coup d'œil + +| | GitHub | Azure DevOps | GitLab | +|---|:---:|:---:|:---:| +| Barre d'outils, saisie au clavier, pastille de validation | Oui | Oui | Oui, dans l'éditeur Markdown seulement | +| Badges sur les commentaires publiés | Oui | Oui | Oui | +| Bandeau des fils bloquants non résolus | Oui | Oui | Oui | +| Filtre des fils | Oui | Oui | Oui, sauf dans l'onglet *Changes* | +| Lit le `.conventional-comments.json` du dépôt | Oui | Oui | **Pas encore** | +| Blocage de l'envoi (`enforce`) | Oui | Oui | **Non** | +| Un commentaire général peut ouvrir un fil bloquant | Non | Oui | Oui, s'il est publié avec *Start thread* | +| Corps d'une revue soumise en bloc | Oui | N'existe pas | Oui | +| Bloc de suggestion lu comme une `suggestion` | Oui | Oui | Pas encore | + +## Domaines + +| Offre | Domaine | Dans la page de réglages | +|---|---|---| +| GitHub.com | `github.com` | *Domaines connus*, un clic | +| GitHub Enterprise Cloud avec résidence des données | votre propre sous-domaine de `ghe.com` | *Autres domaines* : saisissez-le, choisissez GitHub | +| GitHub Enterprise Server | votre propre domaine | *Autres domaines* : saisissez-le, choisissez GitHub | +| Azure DevOps Services | `dev.azure.com` | *Domaines connus*, un clic | +| Azure DevOps Services, ancienne URL | `.visualstudio.com` | *Autres domaines* : saisissez-le, choisissez Azure DevOps | +| Azure DevOps Server | votre propre domaine | *Autres domaines* : saisissez-le, choisissez Azure DevOps | +| GitLab.com | `gitlab.com` | *Domaines connus*, un clic | +| GitLab Self-Managed, GitLab Dedicated | votre propre domaine | *Autres domaines* : saisissez-le, choisissez GitLab. **Non mesuré.** | + +Aucun domaine n'est accordé à l'installation, pas même `github.com`. Vous saisissez votre +propre sous-domaine au lieu d'autoriser tout `ghe.com` ou tout `visualstudio.com` : +l'extension n'obtient que le seul hôte que vous utilisez. + +## GitHub + +- Les deux pages de pull request sont prises en charge : la page *Conversation* classique et + la nouvelle page *Overview*, ainsi que *Files changed*. +- La conversation générale d'une pull request n'a pas de bouton « résoudre » : un label + bloquant écrit là ne peut donc pas ouvrir un fil bloquant. La pastille le dit avec + `W-NOT-BLOCKABLE`. +- Soumettre une revue valide son corps (`scope.validateReviewSummary`) ; approuver sans texte + reste possible. +- Un fil est résolu quand la conversation est marquée *Resolved*. +- Le fichier du dépôt est lu avec la session de la page : les dépôts privés fonctionnent pour + toute personne connectée qui y a accès. + +## Azure DevOps + +- Tous les boutons d'envoi passent par la validation : *Comment*, *Reply*, *Reply & resolve*, + *Update*, *Update & resolve*, *Reply & reactivate*. +- Un commentaire général est un fil doté d'un statut, comme un commentaire sur une ligne : un + label bloquant y compte parmi les fils bloquants. +- Un fil compte comme non résolu tant que son statut est *Active* ou *Pending*, ou quand il + n'en a aucun. Tout autre statut compte comme résolu. +- Il n'y a pas de corps de revue : `scope.validateReviewSummary` est ignorée. +- Les commentaires de pipeline sont publiés par `Project Collection Build Service ()` ou + ` Build Service ()` : ce sont les noms à mettre dans `exemptUsers`. + +## GitLab + +Mesuré sur gitlab.com seulement. + +- **L'extension ne lit pas encore le fichier du dépôt sur GitLab.** Elle applique les valeurs + par défaut du produit, affiche *Configuration non lue*, et **ne bloque donc jamais un + envoi** sur cette plateforme, quel que soit le mode. +- **Seul l'éditeur Markdown est géré.** GitLab laisse chaque personne basculer vers un éditeur + de texte enrichi et mémorise ce choix. Dans cet éditeur, l'extension se tient entièrement à + l'écart : ni barre d'outils, ni validation. Revenez en arrière avec *Switch to plain text + editing*, sous le champ. +- Un commentaire général publié avec *Start thread* est un fil résoluble et peut être + bloquant. Publié avec *Comment*, c'est une simple note : un label bloquant n'y est pas + compté, et aucun avertissement ne le dit. +- Dans l'onglet *Changes*, le filtre des fils n'est pas affiché, et les fils résolus ne sont + pas dans la page pour que l'extension les lise. +- GitLab Self-Managed et GitLab Dedicated n'ont pas été mesurés. + +## Navigateurs + +| Navigateur | Version | +|---|---| +| Chrome, Edge, autres navigateurs Chromium | Les trois dernières versions majeures | +| Firefox | 128 ou ultérieure | diff --git a/docs/guide/review-skills-en.md b/docs/guide/review-skills-en.md new file mode 100644 index 00000000..835d2dcb --- /dev/null +++ b/docs/guide/review-skills-en.md @@ -0,0 +1,59 @@ +# Review skills for AI agents + +**Languages:** English (this file) | [Français](review-skills-fr.md) + +Two skills let an AI agent take part in a review the way this toolkit expects: one for the +agent that reviews, one for the agent that answers. Each is a directory under +[`skills/`](../../skills), whose `SKILL.md` Claude Code loads as is and any other agent can +be given as instructions. + +| Skill | For | What the agent does | +|---|---|---| +| [`review-pull-request`](../../skills/review-pull-request/SKILL.md) | The **reviewer** | Publishes its findings as Conventional Comments, rated P0 to P3, follows them up until each fix is verified, and closes its review with `reviewed:` once nothing is left. | +| [`respond-to-review`](../../skills/respond-to-review/SKILL.md) | The **author** of the pull request | Answers every finding and question with `done:`, `ack:`, `disagree:` or `thanks:` (or `note:` to inform, `question:` to ask back) and pushes the fixes. | + +Neither approves nor merges: those stay human decisions. The author's skill never posts +`reviewed` or `decision`. + +Both read the repository's `.conventional-comments.json` first, so they only use the labels +it enables. + +## Install + +Install or hand over **the whole directory**, not the `SKILL.md` alone: the reviewer's skill +relies on the files beside it, which say how review-session identifiers are chosen. + +## Review sessions + +When several agents, or several runs of one account, review the same pull request, the +platform says who wrote a comment but not which session produced it. The reviewer therefore +ends each of its comments with a marker line, the same for its whole session: + +```text +issue (blocking): the retry loop never stops on a 4xx answer + +A 404 is retried forever. + +[session:disheartening-reviewed-implementation] +``` + +The author's skill copies the marker into its reply to that comment. The extension hides the +line and shows `🤖 session: disheartening-reviewed-implementation` at the bottom of the +comment ([writing review comments](writing-comments-en.md#once-comments-are-published)). + +- Each session draws its own identifier from a random source and checks that the pull + request does not carry it yet. It never takes one from the pull request, from another + session or from an earlier conversation. +- The identifier is a readable name drawn by [Slugger](https://github.com/Reefact/slugger), + or a GUID. The choice is made once per installation and recorded in a `session-id.md` file + committed beside the skill; where none is recorded yet, the reviewer's skill offers Slugger + once and records the answer. +- A Slugger name can carry a description, one sentence that renders its words, after an em + dash and in italics. The extension shows the name, and the sentence on hover: + + ```text + [session:disheartening-reviewed-implementation — *We reviewed the implementation, and frankly, it was disheartening.*] + ``` + +A marker is optional metadata. It is removed before validation and changes no verdict; a +comment with more than one marker designates no session and gets a warning. diff --git a/docs/guide/review-skills-fr.md b/docs/guide/review-skills-fr.md new file mode 100644 index 00000000..721001c0 --- /dev/null +++ b/docs/guide/review-skills-fr.md @@ -0,0 +1,62 @@ +# Skills de revue pour agents IA + +**Langues :** [English](review-skills-en.md) | Français (ce fichier) + +Deux skills permettent à un agent IA de prendre part à une revue comme ce toolkit l'attend : +un pour l'agent qui relit, un pour l'agent qui répond. Chacun est un répertoire sous +[`skills/`](../../skills), dont le `SKILL.md` est chargé tel quel par Claude Code et peut être +donné comme instructions à n'importe quel autre agent. + +| Skill | Pour | Ce que fait l'agent | +|---|---|---| +| [`review-pull-request`](../../skills/review-pull-request/SKILL.md) | Le **relecteur** | Publie ses constats sous forme de Conventional Comments, cotés de P0 à P3, les suit jusqu'à ce que chaque correction soit vérifiée, et clôt sa revue avec `reviewed:` quand il ne reste rien. | +| [`respond-to-review`](../../skills/respond-to-review/SKILL.md) | L'**auteur** de la pull request | Répond à chaque constat et à chaque question avec `done:`, `ack:`, `disagree:` ou `thanks:` (ou `note:` pour informer, `question:` pour demander en retour) et pousse les corrections. | + +Aucun des deux n'approuve ni ne fusionne : ces décisions restent humaines. Le skill de +l'auteur ne publie jamais `reviewed` ni `decision`. + +Tous deux lisent d'abord le `.conventional-comments.json` du dépôt, et n'utilisent donc que +les labels qu'il active. + +## Installer + +Installez ou transmettez **le répertoire entier**, pas le seul `SKILL.md` : le skill du +relecteur s'appuie sur les fichiers qui l'accompagnent, qui disent comment sont choisis les +identifiants de session de revue. + +## Sessions de revue + +Quand plusieurs agents, ou plusieurs exécutions d'un même compte, relisent la même pull +request, la plateforme dit qui a écrit un commentaire mais pas quelle session l'a produit. Le +relecteur termine donc chacun de ses commentaires par une ligne de marqueur, la même pour +toute sa session : + +```text +issue (blocking): la boucle de reprise ne s'arrête jamais sur une réponse 4xx + +Un 404 est retenté indéfiniment. + +[session:disheartening-reviewed-implementation] +``` + +Le skill de l'auteur recopie le marqueur dans sa réponse à ce commentaire. L'extension masque +la ligne et affiche `🤖 session: disheartening-reviewed-implementation` en bas du commentaire +([rédiger des commentaires de revue](writing-comments-fr.md#une-fois-les-commentaires-publiés)). + +- Chaque session tire son propre identifiant d'une source aléatoire et vérifie que la pull + request ne le porte pas déjà. Elle n'en reprend jamais un de la pull request, d'une autre + session ou d'une conversation antérieure. +- L'identifiant est un nom lisible tiré par [Slugger](https://github.com/Reefact/slugger), + ou un GUID. Le choix est fait une fois par installation et consigné dans un fichier + `session-id.md` commité à côté du skill ; quand rien n'est encore consigné, le skill du + relecteur propose Slugger une fois et consigne la réponse. +- Un nom Slugger peut porter une description, une phrase qui reprend ses mots, après un tiret + cadratin et en italique. L'extension affiche le nom, et la phrase au survol : + + ```text + [session:disheartening-reviewed-implementation — *We reviewed the implementation, and frankly, it was disheartening.*] + ``` + +Un marqueur est une métadonnée facultative. Il est retiré avant la validation et ne change +aucun verdict ; un commentaire qui porte plus d'un marqueur ne désigne aucune session et +reçoit un avertissement. diff --git a/docs/guide/settings-en.md b/docs/guide/settings-en.md new file mode 100644 index 00000000..f0d5902d --- /dev/null +++ b/docs/guide/settings-en.md @@ -0,0 +1,72 @@ +# The settings page + +**Languages:** English (this file) | [Français](settings-fr.md) + +The extension's settings page opens by itself after the installation. Afterwards, click the +extension's icon in the browser toolbar (pin it from the puzzle-piece menu if it is hidden). +A **Guided tour** button, at the top, replays the introduction. + +The page sets what belongs to **you**: which sites the extension may work on, and a few +personal preferences. The mode and the list of labels are not here. They belong to the team +and live in the repository's [configuration](configuration-en.md). + +## Allowed domains + +The extension works on the domains listed here, and only on them. Until one is allowed, it is +inactive everywhere. + +| Panel | What it does | +|---|---| +| **Known domains** | GitHub.com, Azure DevOps Services, GitLab.com. One click grants access; the browser asks you to confirm. | +| **Other domains** | For a host of your own. Type the domain, choose the platform that serves it, then **Allow**. Choose *Other (organisation configuration host only)* for a host that only serves your organisation's configuration. | +| **Configured domains** | What you allowed. **Withdraw** removes the access. A domain marked *enterprise policy* was set by your organisation and cannot be withdrawn here. | +| **Unconfigured domains** | Domains that got access from the browser's own *Site access* menu, with no platform. The extension does nothing on them until you associate a platform, or withdraw the access. | + +[Which domain for which platform](platforms-en.md#domains). + +## Local preferences + +| Preference | What it does | +|---|---| +| **Interface language** | English or French. By default the extension follows the repository's configuration, then the platform's language; this setting comes first, for you alone. | +| **Direct shortcuts** | `Alt` + letter combinations that insert a label. One per line, such as `Alt+R=reviewed`; `Alt+D=` disables a shipped shortcut. See [keyboard input](keyboard-input-en.md#direct-shortcuts). | +| **Button order** | Labels to put first in the toolbar, separated by commas: `suggestion,nitpick,disagree`. The labels you list come first in their own row; the others follow in the default order. The completion list follows the same order. | + +These preferences follow you through your browser's sync, if it is on. Shortcuts and button +order apply to the next comment field that opens. + +## Added labels + +The six labels the extension adds to Conventional Comments (`thanks`, `done`, `ack`, +`disagree`, `summary`, `reviewed`) are enabled by default. This section shows the +configuration block that disables them, and **Copy the configuration** puts it in your +clipboard. + +The button disables nothing by itself: the block goes into the repository's +`.conventional-comments.json`, which the whole team shares. With no existing file, the block +can be the whole file; otherwise add its six entries to the existing `labels` list +([why these labels exist](labels-en.md#labels-that-are-not-part-of-conventional-comments)). + +## Telemetry + +Off by default, and the box stays inert until your organisation declares a collection +endpoint through its enterprise policy. The page shows that endpoint before you agree. Only +aggregate counters are sent, never the text of a comment, of code or of a diff, nor the +address of the page ([privacy policy](../../PRIVACY.md)). + +## Status + +Where to look when something does not behave as expected. + +- **Configuration:** whether the last read succeeded, and the configuration notices of that + read, with the repository they concern. +- **Journal:** the things the extension looked for in a page and did not find (a comment + field, a send button, a thread anchor…) and the errors it caught. An entry says what was + looked for, not why it was missing: a button that is absent on a closed pull request is + normal. +- **Download the diagnostic (.zip):** an archive to attach to a bug report. It holds the + journal and, for each element not found, a skeleton of the page: tags and a short list of + interface attributes, never the text of a comment, of code or of a field. **Read + `report.json` before sharing it:** page addresses name repositories and pull requests, and + an interface label can name an account. +- **Clear the log** empties the journal. diff --git a/docs/guide/settings-fr.md b/docs/guide/settings-fr.md new file mode 100644 index 00000000..38e736c6 --- /dev/null +++ b/docs/guide/settings-fr.md @@ -0,0 +1,76 @@ +# La page de réglages + +**Langues :** [English](settings-en.md) | Français (ce fichier) + +La page de réglages de l'extension s'ouvre d'elle-même après l'installation. Ensuite, cliquez +sur l'icône de l'extension dans la barre d'outils du navigateur (épinglez-la depuis le menu en +forme de pièce de puzzle si elle est masquée). Un bouton **Visite guidée**, en haut, rejoue +l'introduction. + +La page règle ce qui **vous** appartient : les sites sur lesquels l'extension peut travailler, +et quelques préférences personnelles. Le mode et la liste des labels ne sont pas ici. Ils +appartiennent à l'équipe et vivent dans la [configuration](configuration-fr.md) du dépôt. + +## Domaines autorisés + +L'extension fonctionne sur les domaines listés ici, et sur eux seulement. Tant qu'aucun n'est +autorisé, elle est inactive partout. + +| Panneau | Ce qu'il fait | +|---|---| +| **Domaines connus** | GitHub.com, Azure DevOps Services, GitLab.com. Un clic accorde l'accès ; le navigateur vous demande de confirmer. | +| **Autres domaines** | Pour un hôte qui vous est propre. Saisissez le domaine, choisissez la plateforme qui le sert, puis **Autoriser**. Choisissez *Autre (hôte de configuration d’organisation uniquement)* pour un hôte qui ne sert que la configuration de votre organisation. | +| **Domaines configurés** | Ce que vous avez autorisé. **Retirer** supprime l'accès. Un domaine marqué *politique d’entreprise* a été fixé par votre organisation et ne peut pas être retiré ici. | +| **Domaines non configurés** | Des domaines qui ont reçu un accès depuis le menu *Accès au site* du navigateur lui-même, sans plateforme. L'extension n'y fait rien tant que vous ne leur associez pas une plateforme, ou que vous ne retirez pas l'accès. | + +[Quel domaine pour quelle plateforme](platforms-fr.md#domaines). + +## Préférences locales + +| Préférence | Ce qu'elle fait | +|---|---| +| **Langue de l’interface** | Anglais ou français. Par défaut, l'extension suit la configuration du dépôt, puis la langue de la plateforme ; ce réglage passe devant, pour vous seul. | +| **Raccourcis directs** | Des combinaisons `Alt` + lettre qui insèrent un label. Une par ligne, par exemple `Alt+R=reviewed` ; `Alt+D=` désactive un raccourci livré. Voir la [saisie au clavier](keyboard-input-fr.md#raccourcis-directs). | +| **Ordre des boutons** | Les labels à placer en tête dans la barre d'outils, séparés par des virgules : `suggestion,nitpick,disagree`. Les labels que vous listez passent en tête de leur propre rangée ; les autres suivent dans l'ordre par défaut. La liste de complétion suit le même ordre. | + +Ces préférences vous suivent grâce à la synchronisation de votre navigateur, si elle est +activée. Les raccourcis et l'ordre des boutons s'appliquent au prochain champ de commentaire +qui s'ouvre. + +## Labels ajoutés + +Les six labels que l'extension ajoute à Conventional Comments (`thanks`, `done`, `ack`, +`disagree`, `summary`, `reviewed`) sont activés par défaut. Cette section affiche le bloc de +configuration qui les désactive, et **Copier la configuration** le place dans votre +presse-papiers. + +Le bouton ne désactive rien par lui-même : le bloc va dans le fichier +`.conventional-comments.json` du dépôt, que toute l'équipe partage. Sans fichier existant, le +bloc peut constituer le fichier entier ; sinon, ajoutez ses six entrées à la liste `labels` +existante +([pourquoi ces labels existent](labels-fr.md#les-labels-qui-ne-font-pas-partie-de-conventional-comments)). + +## Télémétrie + +Désactivée par défaut, et la case reste inerte tant que votre organisation n'a pas déclaré de +point de collecte dans sa politique d'entreprise. La page affiche ce point de collecte avant +que vous ne donniez votre accord. Seuls des compteurs agrégés sont envoyés, jamais le texte +d'un commentaire, d'un code ou d'un diff, ni l'adresse de la page +([politique de confidentialité](../../PRIVACY.md)). + +## État + +Là où regarder quand quelque chose ne se comporte pas comme prévu. + +- **Configuration :** si la dernière lecture a réussi, et les avis de configuration de cette + lecture, avec le dépôt qu'ils concernent. +- **Journal :** ce que l'extension a cherché dans une page sans le trouver (un champ de + commentaire, un bouton d'envoi, l'ancre d'un fil…) et les erreurs qu'elle a interceptées. + Une entrée dit ce qui était cherché, pas pourquoi cela manquait : un bouton absent sur une + pull request fermée est normal. +- **Télécharger le diagnostic (.zip) :** une archive à joindre à un rapport de bug. Elle + contient le journal et, pour chaque élément non trouvé, un squelette de la page : des + balises et une courte liste d'attributs d'interface, jamais le texte d'un commentaire, d'un + code ou d'un champ. **Relisez `report.json` avant de la partager :** les adresses de page + nomment des dépôts et des pull requests, et un libellé d'interface peut nommer un compte. +- **Effacer le journal** vide le journal. diff --git a/docs/guide/writing-comments-en.md b/docs/guide/writing-comments-en.md new file mode 100644 index 00000000..44331e17 --- /dev/null +++ b/docs/guide/writing-comments-en.md @@ -0,0 +1,157 @@ +# Writing review comments + +**Languages:** English (this file) | [Français](writing-comments-fr.md) + +What the extension adds to a pull request page: a toolbar and a status pill while you write, +badges, a banner and a filter once comments are published. + +## The format + +A review comment starts with a prefix line: + +```text +