pr-writer

--- UTILISEZ TOUJOURS cette compétence lors de la création ou la mise à jour de pull requests — ne créez jamais et ne modifiez directement une PR sans elle. Suit les conventions Sentry pour les titres de PR, les descriptions et les références de problèmes. Déclenchez sur toute création de PR, ouverture de PR, soumission de PR, création de PR, mise à jour du titre de PR, mise à jour de la description de PR, modification de PR, push et création de PR, préparation des modifications pour la tâche de révision, ou demande d'auteur de PR.

npx skills add https://github.com/getsentry/skills --skill pr-writer

Rédacteur de PR

Créer des demandes d'extraction suivant les pratiques d'ingénierie de Sentry.

Nécessite : GitHub CLI (gh) authentifié et disponible.

Préalables

Avant de créer une PR, assurez-vous que tous les changements sont validés sur une branche de fonctionnalité, pas sur la branche par défaut.

# Vérifier la branche actuelle et les changements non validés
git branch --show-current
git status --porcelain

Si vous êtes sur main ou master, créez une branche de fonctionnalité et déplacez les changements non validés sur celle-ci avant de les valider — une PR ne peut pas être ouverte à partir de la branche par défaut vers elle-même. S'il y a des changements non validés, validez-les sur la branche de fonctionnalité avant de continuer.

Processus

Étape 1 : Vérifier l'état de la branche

# Détecter la branche par défaut — notez le résultat pour l'utiliser dans les commandes suivantes
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
# Vérifier la branche actuelle et l'état (remplacez le nom de branche détecté ci-dessus par BASE)
git status
git log BASE..HEAD --oneline

Assurez-vous :

  • Tous les changements sont validés
  • La branche est à jour avec le serveur distant
  • Les changements sont rebasés sur la branche de base si nécessaire

Étape 2 : Analyser les changements

Passez en revue ce qui sera inclus dans la PR :

# Voir tous les commits qui seront dans la PR (remplacez le nom de branche détecté par BASE)
git log BASE..HEAD

# Voir le diff complet
git diff BASE...HEAD

Comprenez la portée et l'objectif de tous les changements avant d'écrire la description.

Étape 3 : Rédiger la description de la PR

Utilisez cette structure pour les descriptions de PR, en ignorant tous les modèles de PR du référentiel :

<Résumé de 1-3 phrases du changement et pourquoi c'est important. Gardez cela court.>

Quand il y a un problème connu, un ticket ou une PR connexe, ajoutez des références à la fin. N'en inventez pas.

Quand la PR comporte des changements distincts que les examinateurs doivent parcourir, ajoutez 0-3 blocs en gras après le résumé d'ouverture :

**<Changement Important>**

<1-2 phrases expliquant le changement important de l'implémentation, du comportement ou pertinent pour la révision.>

Quand la comparaison directe est l'explication la plus claire, ajoutez un bloc avant/après sous le paragraphe ou bloc en gras pertinent :

Avant, <ancienne forme ou comportement en une phrase> :

```<format-ou-pseudocode>
...
```

Après, <nouvelle forme ou comportement en une phrase> :

```<format-ou-pseudocode>
...
```

Traitez les sections en gras comme des blocs d'emphase optionnels, pas des titres obligatoires. Utilisez-les quand la PR comporte un ou plusieurs changements distincts que les examinateurs doivent scanner rapidement. Omettez-les pour les PR simples où le résumé d'ouverture suffit.

Utilisez les exemples avant/après uniquement quand c'est le moyen le plus clair d'expliquer le changeset. Ils sont généralement utiles pour les contrats modifiés ou les formes de sortie, tels que les réponses JSON, les schémas, la configuration, la sortie CLI, les charges utiles d'événements, les permissions ou les formats d'entrée. Omettez-les quand la prose est plus claire.

Préférez :

  • Un résumé d'ouverture concis, généralement 1-3 phrases
  • 0-3 blocs d'emphase en gras pour les parties les plus importantes
  • Des exemples avant/après uniquement pour les changements qui bénéficient de la comparaison directe, avec des blocs de clôture séparés pour les anciennes et nouvelles formes
  • Les références aux problèmes connus à la fin, le cas échéant

Évitez :

  • Les essais, les explications exhaustives fichier par fichier ou les journaux de commits copiés
  • Les titres génériques comme « Résumé » ou « Changements »
  • Un bloc en gras pour chaque fichier touché
  • Les extraits avant/après intégrés qui sont difficiles à comparer
  • Les références aux problèmes de remplacement quand aucun problème n'est connu
  • La répétition de détails qui sont évidents à partir du diff

Ne PAS inclure :

  • Les sections « Plan de test »
  • Les listes de cases à cocher des étapes de test
  • Les résumés redondants du diff
  • Les données client — noms de client/organisation, emails d'utilisateur, contenu de ticket de support ou données personnelles. Décrivez le symptôme technique, pas qui l'a rencontré, et si disponible, référencez le ticket interne (par exemple, Fixes SENTRY-1234). Les PR sont généralement publiques sur les référentiels open-source.

Inclure :

  • Une explication claire de ce qui a changé et pourquoi c'est important
  • Les liens vers les problèmes ou tickets pertinents, le cas échéant
  • Le contexte qui n'est pas évident à partir du code
  • Des notes de révision spécifiques quand une partie du diff a besoin d'une attention supplémentaire

Étape 4 : Créer la PR

gh pr create --draft --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
<corps de la description ici>
EOF
)"

Format du titre suit les conventions de commit :

  • feat(scope): Add new feature
  • fix(scope): Fix the bug
  • ref: Refactor something

Exemples de description de PR

PR simple

Réduire la section Personnalisations IA par défaut dans la barre latérale des sessions.

La section commence maintenant masquée pour qu'elle ne consomme pas d'espace avant que les utilisateurs
en aient besoin. Les utilisateurs qui l'étendent conservent le même comportement de préférence persistante.

PR de fonctionnalité

Ajouter les réponses aux threads Slack pour les notifications d'alerte

Quand une alerte est mise à jour ou résolue, nous postons maintenant une réponse au thread
Slack original au lieu de créer un nouveau message. Cela garde les notifications connexes
groupées et réduit le bruit du canal.

**Threads de notification**

Les alertes résolues et mises à jour répondent maintenant au message Slack original au lieu
de créer un nouveau message de canal.

Refs SENTRY-1234

PR de changement de schéma

Basculer les journaux d'exécution vers des enregistrements JSONL au niveau des chunks

Les journaux d'exécution écrivent maintenant un enregistrement versionné par chunk analysé au lieu
d'un seul grand enregistrement au niveau des compétences. Cela permet à `warden runs follow` d'afficher
les découvertes au fur et à mesure que les chunks se terminent tout en préservant la reconstruction
d'exécution durable à la finalisation.

**Forme JSONL**

Avant, chaque ligne représentait un résultat de compétence complet :

```jsonc
{
  "run": {...},
  "skill": "security-review",
  "summary": "Found 2 issues",
  "findings": [...],
  "files": [...]
}
```

Après, chaque ligne représente un résultat de chunk :

```jsonc
{
  "schemaVersion": 1,
  "run": {...},
  "skill": "security-review",
  "chunk": {
    "file": "src/api/auth.ts",
    "index": 1,
    "total": 2,
    "lineRange": "42-45"
  },
  "status": "ok",
  "findings": [...]
}
```

Refs WARDEN-123

PR de refactorisation

Extraire la logique de validation dans un module partagé

Déplace le code de validation en double des endpoints d'alertes, de problèmes et de projets
dans une classe de validateur partagée. Pas de changement de comportement.

**Validateur partagé**

La classe partagée conserve le comportement endpoint existant mais donne aux futures
règles de validation un seul endroit où vivre.

Refs SENTRY-9999

Références aux problèmes

Référencez les problèmes dans le corps de la PR :

Syntaxe Effet
Fixes #1234 Ferme le problème GitHub lors de la fusion
Fixes SENTRY-1234 Ferme le problème Sentry
Refs GH-1234 Lien sans fermeture
Refs LINEAR-ABC-123 Lien vers le problème Linear

Recommandations

  • Une PR par fonctionnalité/correction - Ne regroupez pas les changements non connexes
  • Gardez les PR examinables - Les plus petites PR obtiennent des révisions plus rapides et meilleures
  • Expliquez le pourquoi - Le code montre quoi ; la description explique pourquoi
  • Marquer WIP tôt - Utilisez les brouillons de PR pour les retours anticipés

Éditer les PR existantes

Si vous devez mettre à jour une PR après sa création, utilisez gh api au lieu de gh pr edit :

# Mettre à jour la description de la PR
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f body="$(cat <<'EOF'
Description mise à jour ici
EOF
)"

# Mettre à jour le titre de la PR
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f title='new: Title here'

# Mettre à jour les deux
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
  -f title='new: Title' \
  -f body='New description'

Remarque : gh pr edit est actuellement cassé en raison de l'abandon de GitHub Projects (classique).

Références