Craft Repository README

Lisez-moi du référentiel du référentiel de l'artisanat

Transformez un dépôt en une page d'accueil claire et crédible. Fondez chaque affirmation, commande, badge et lien sur le projet réel ; le polissage visuel ne doit jamais dépasser la précision.

Choisir le mode de fonctionnement

• Utilisez le mode audit lorsque l'utilisateur demande uniquement un retour. Inspectez et rapportez ; ne modifiez pas et ne publiez pas.
• Utilisez le mode construction lorsque l'utilisateur demande de créer ou d'améliorer le README. Modifiez le dépôt et validez le résultat.
• Utilisez le mode publication uniquement lorsque l'utilisateur demande de valider, pousser, ouvrir une pull request ou modifier les paramètres du dépôt. Suivez le flux de travail Git normal du dépôt.

1. Inspecter le projet réel

Avant de rédiger, inspectez :

• Les fichiers README* existants, de contribution, de sécurité, de licence, de changelog et de déploiement.
• Les manifests de paquets, les points d'entrée, les fichiers d'environnement d'exemple, les commandes de test, les captures d'écran, les logos et les URL publiques.
• Le remote Git, la branche par défaut, les tags de version, les workflows CI et la configuration d'hébergement.
• Les instructions au niveau du dépôt telles que AGENTS.md ou CONTRIBUTING.md.

Dérivez le nom du produit, la proposition de valeur en une phrase, le public cible, les plateformes supportées, les commandes d'installation, les commandes d'exécution et le récit de déploiement à partir des preuves. Si un fait matériel ne peut être vérifié, omettez-le ou étiquetez-le clairement comme prévu.

2. Effectuer une vérification de portée publique et de sécurité

Considérez le travail sur le README comme une revue de publication. Avant d'exposer des détails :

• Recherchez dans les fichiers suivis et les modifications en attente les clés API, les clés privées, les jetons, les mots de passe, les cookies, les noms d'hôte internes, les IP privées et les chemins personnels.
• Ne collez jamais de secrets provenant de la configuration locale, de l'historique des conversations, de l'historique du shell ou des fichiers de déploiement.
• Liez vers .env.example ; ne reproduisez jamais les valeurs de .env.
• Confirmez que les captures d'écran, les codes QR, les noms et les liens de contact sont intentionnellement publics.
• Préservez les avis de licence, de marque déposée, d'attribution et d'actifs tiers.

Arrêtez-vous et signalez un blocage concret si la publication exposerait des documents sensibles.

3. Concevoir l'histoire avant la décoration

Rédigez le README pour cette séquence :

1. Reconnaître — nom, logo, promesse concise.
2. Faire confiance — un petit ensemble de badges véridiques et un visuel de produit réel.
3. Comprendre — ce qu'il fait, à qui il s'adresse et sa principale différence.
4. Essayer — le chemin le plus court vérifié du clone au résultat fonctionnel.
5. Adopter — configuration, déploiement, architecture, limitations et support.
6. Participer — contribution, sécurité, licence, sponsors et communauté.

Consultez references/readme-patterns.md avant de reconstruire une mise en page README ou de sélectionner des badges.

4. Construire un en-tête compact et de marque

Utilisez cet ordre lorsque le projet dispose des actifs pour le supporter :

1. Logo lié avec un texte alternatif descriptif et une taille d'affichage restreinte.
2. Nom du projet et proposition de valeur en une ligne.
3. Quatre à huit badges significatifs.
4. Liens principaux tels que démo en direct, documentation, suivi des problèmes ou téléchargement.
5. Navigation facultative dans la page pour un long README.
6. Une image héroïque forte, une capture d'écran du produit ou une courte démo.

Préférez les actifs appartenant au dépôt sous un chemin stable docs/, .github/ ou assets/. Réutilisez un logo existant avant d'en générer un nouveau. Si l'utilisateur demande un nouveau visuel et qu'une compétence de génération d'image est disponible, utilisez-la, puis optimisez le résultat pour l'affichage dans le dépôt.

N'utilisez pas de faux badges de build, de métriques de placeholder, de murs de badges géants, de compteurs décoratifs ou d'actifs liés à chaud que le projet ne contrôle pas.

5. Sélectionner uniquement les sections utiles

Un projet compact a normalement besoin de :

• Ce qu'il est et pourquoi il existe.
• Points forts des fonctionnalités ancrés dans le comportement implémenté.
• Démarrage rapide avec des commandes copiables et testées.
• Configuration utilisant des espaces réservés sécurisés.
• Captures d'écran ou démo lorsque la preuve visuelle aide matériellement.
• Notes de déploiement ou de production lorsque le projet est déployable.
• Liens vers la contribution, la sécurité, la licence et les remerciements lorsque ces fichiers existent.

Ajoutez l'architecture, la référence API, la compatibilité, la feuille de route, la FAQ ou le dépannage uniquement lorsque le projet le justifie. Ne créez pas de sections vides et génériques.

Pour les projets chinois, rédigez d'abord en chinois naturel et conservez les identifiants techniques dans leur forme originale. Ajoutez une version anglaise uniquement sur demande ou lorsque le dépôt en maintient déjà une.

6. Ajouter le parrainage sans perturber l'histoire du produit

Lorsque l'utilisateur fournit et autorise une image ou un code QR de sponsor :

• Copiez-le dans un chemin d'actif stable appartenant au dépôt.
• Utilisez un titre clair tel que 支持项目 ou Sponsor près de la partie inférieure du README.
• Ajoutez un texte alternatif, une largeur raisonnable et une phrase expliquant ce que le soutien finance.
• Ne modifiez, décodez ou régénérez jamais un code QR de paiement sauf demande explicite.

Ne laissez pas le parrainage surpasser le démarrage rapide, la documentation ou les informations de sécurité.

7. Vérifier le README comme documentation exécutable

Exécutez les commandes de build, test, lint ou smoke pertinentes du projet lorsque c'est pratique. Ensuite, exécutez le vérificateur intégré :

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md

Ajoutez des indicateurs stricts lorsque les éléments correspondants sont requis :

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md \
  --require-logo --require-badges --require-hero --require-sponsor

Vérifiez également manuellement :

• Chaque commande d'installation et d'exécution correspond au dépôt.
• Les liens d'image et de document relatifs se résolvent avec les chemins sensibles à la casse de GitHub.
• Les liens externes utilisent les domaines canoniques prévus.
• Les ancres d'en-tête et les liens de table des matières fonctionnent.
• Les images ont un texte alternatif descriptif et des dimensions raisonnables.
• Le README s'affiche bien sur les écrans larges et étroits.
• Aucun secret, placeholder, chemin absolu local ou affirmation non vérifiée ne subsiste.

8. Publier délibérément

Lorsque la publication est dans le périmètre :

• Passez en revue git diff et gardez les modifications non liées hors du commit.
• Commitez avec un message ciblé et poussez via le flux de travail normal du dépôt.
• Préférez une pull request lorsque les protections de branche ou les pratiques de collaboration l'exigent.
• Mettez à jour la description GitHub, la page d'accueil, les sujets et l'aperçu social uniquement lorsque l'utilisateur a demandé des modifications des paramètres du dépôt et que les valeurs sont vérifiées.
• Rouvrez le README rendu sur GitHub après la publication et vérifiez les images, les badges, les liens et la mise en page mobile.

Critères d'achèvement

• Le premier écran communique le nom, l'objectif, les signaux de confiance et l'action principale suivante.
• Toutes les affirmations et commandes importantes sont vérifiées par rapport au dépôt.
• Le logo, l'image héroïque, les badges et le contenu du sponsor sont intentionnels plutôt qu'ornementaux.
• Les liens et les actifs locaux se résolvent.
• Aucun détail secret ou d'environnement privé n'est exposé.
• La validation réussit et l'étape de publication demandée est terminée.