Guide de rédaction d'issues : bonnes pratiques observées

[HumanistAtypik]

Contexte

Après analyse des 64 issues existantes du projet, voici un guide des bonnes pratiques de rédaction qui maximisent l'impact et la rapidité de résolution.

Structure du titre

Format recommandé : [préfixe optionnel]: description concise du problème/amélioration

Préfixes observés :

• improvment: pour améliorations UX ou conformité standards
• Aucun préfixe pour bugs critiques
• Titre direct pour questions légitimes

Exemples performants :

• "Config file contains secrets but is readable by all" (Config file contains secrets but is readable by all #13)
• "improvment: shai config should respect XDG_CONFIG" (improvment: shai config should respect XDG_CONFIG #3)
• "shai version in banner shall be computed and not hardcoded" (shai version in banner shall be computed and not hardcoded #47)

Structure du corps

Pour bugs critiques

[Description contexte en 1 phrase]

[Bloc code avec erreur complète]

[Informations système pertinentes si applicable]

Exemple : #1 inclut message d'erreur bash, sortie lscpu complète, et erreur de compilation Rust.

Pour améliorations architecturales

[Proposition en phrase d'introduction]

- aspect spécifique 1
- aspect spécifique 2
- aspect spécifique 3
- aspect spécifique 4

[Phrase de conclusion sur l'usage]

Exemple : #40 structure la demande d'agents spécialisés avec 4 bullets (modèle, prompt, outils, output).

Pour problèmes de sécurité

[État actuel avec valeur technique précise]
[Justification du risque]
[Solution proposée avec valeur technique précise]

Exemple : #13 mentionne permissions 644 actuelles, risque API keys, solution 600 proposée.

Pour bugs multi-plateformes

[Contexte environnement en première ligne]

[Bloc erreur avec trace complète]

[Hypothèse technique si pertinente]

Exemple : #21 précise "On Alpine Linux (using musl libc)" suivi de l'erreur Rust complète.

Éléments visuels

• Captures d'écran : Pour problèmes UX (diff view in edit permission modal #16 montre le problème avec image haute résolution)
• Vidéos : Pour bugs d'affichage complexes (invisible model in list #11 illustre modèle invisible)

Liens techniques stratégiques

• Référence code source : Lien GitHub vers ligne exacte (shai version in banner shall be computed and not hardcoded #47 pointe directement vers le code concerné)
• Standards externes : Spécifications officielles (improvment: shai config should respect XDG_CONFIG #3 référence freedesktop.org)

Ton et approche

• Minimalisme collaborateurs : Descriptions ultra-concises pour équipe
• Détail externe : Contributeurs externes fournissent contexte système complet
• Humanisation : "as a dumb user" légitime l'expérience utilisateur
• Proposition constructive : Toujours suggérer solution concrète

Indicateurs de succès observés

Résolution rapide : 1-4 jours pour issues bien rédigées

Signaux d'impact code :

• Titre référençant fichier/fonction spécifique
• Valeurs techniques précises (permissions, types, versions)
• Erreurs complètes non tronquées
• Proposition implémentable immédiatement

Métriques d'engagement

• 2 👍 pour meilleures améliorations UX
• 5-7 commentaires pour discussions architecturales
• Issues What does "yolo" mean? #14, diff view in edit permission modal #16, Error: Failed to fetch models: missing field object against OpenWebUI #61 ont généré le plus d'engagement

---

Ce guide synthétise les patterns observés pour aider la communauté à rédiger des issues efficaces.