Polissage de Projet Open Source

Que fait Polissage de Projet Open Source ?

Objectif

Transformer un dossier de projet existant en un dépôt open source de haute qualité en améliorant la documentation publique, les fichiers communautaires, les métadonnées du dépôt et la configuration Git/GitHub, tout en préservant le code source original.

Limites Strictes

• Ne pas modifier le code source original du produit, la logique générée, les tests, les notebooks, les ressources ou le comportement d'exécution, sauf demande explicite de l'utilisateur.
• Les modifications autorisées sont limitées aux métadonnées et à la documentation du projet : README, LICENCE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CHANGELOG, SUPPORT, CITATION, modèles d'issue/PR, notes de version, badges, .gitignore, .gitattributes, .editorconfig, et l'échafaudage des workflows GitHub / documentation.
• Ne jamais inclure de chemins absolus spécifiques à la machine de l'utilisateur dans le README ou les documents publics, comme /home/<utilisateur>/..., /Users/<utilisateur>/..., des chemins de lecteur, des noms d'espaces de travail personnels, des dossiers de téléchargement ou des chemins absolus de projet. Utiliser des chemins relatifs, $HOME, <repo> ou des espaces réservés.
• Par défaut, appliquer la licence MIT lorsqu'aucune licence n'existe et qu'aucune préférence utilisateur n'est spécifiée.
• Par défaut, publier automatiquement sur GitHub en public pour les dossiers sans remote Git. Déterminer le propriétaire/nom cible si nécessaire, puis créer un remote public et effectuer un push des modifications de documentation uniquement après que les vérifications de secrets sont réussies.
• Si une commande réseau/GitHub échoue, réessayer une fois avec le proxy local configuré avant de déclarer l'étape distante bloquée.
• Préserver les documents et fichiers communautaires existants dans la mesure du possible ; les améliorer de manière incrémentielle plutôt que de remplacer un contenu utile.

Entrées à Clarifier en Cas d'Absence

Ne demander que les informations qui affectent de manière significative les actions irréversibles ou publiques :

1. Périmètre cible : chemin du dossier du projet dans l'espace de travail, ou dossier courant si déjà clair.
2. Identité publique : propriétaire GitHub / nom du dépôt avant la création d'un remote s'il ne peut être déduit du dossier et du compte GitHub authentifié.
3. Surcharge de licence : utiliser une licence existante si présente ; sinon appliquer MIT par défaut, sauf si l'utilisateur demande une autre licence.
4. Positionnement du projet : proposition de valeur en une phrase, utilisateurs cibles et maturité si non déduisible du code/de la documentation.
5. Modifications du code source : supposées interdites ; demander avant de toucher à autre chose que les métadonnées ou la documentation.

Procédure

1. Audit de l'État du Projet

• Inspecter la structure du dossier, le README/documentation existant, les manifestes de paquets, les fichiers de build, les exemples, les fichiers de licence et l'état Git.
• Vérifier si .git existe et si un remote est configuré.
• Identifier les fichiers à risque de secrets avant toute création de remote ou push : .env, identifiants, tokens, gros binaires, jeux de données, notes privées, logs locaux et chemins spécifiques à la machine.
• Résumer les forces existantes, les éléments open source manquants et toute incertitude nécessitant une intervention de l'utilisateur.

2. Planifier les Ajouts Non-Code

Créer un plan concis couvrant uniquement le travail autorisé sur la documentation et les métadonnées :

• Améliorations du README en utilisant la compétence create-readme comme base pour la structure, le ton et le Markdown GitHub.
• README bilingue par défaut : après finalisation du README principal (anglais), produire une version chinoise sauvegardée sous README.zh-CN.md et lier les deux. Rédiger le miroir directement ; réserver la compétence baoyu-translate pour les documents longs ou à forte densité terminologique où la cohérence globale des termes est importante.
• Fichiers communautaires : licence MIT par défaut, guide de contribution, code de conduite, politique de sécurité, guide de support, changelog, citation, gouvernance, modèles d'issue, modèle de PR.
• Hygiène du dépôt : .gitignore, .gitattributes, .editorconfig, index de documentation, index d'exemples, badges, description du projet, topics, métadonnées de financement/parrainage si pertinent.
• Configuration Git/GitHub : initialiser Git si absent, créer un remote public si absent, définir la branche par défaut, et effectuer un push des modifications de documentation uniquement après les vérifications de sécurité.

3. Améliorer le README

Utiliser la compétence create-readme pour la création ou la mise à jour du README. S'assurer que le README est concis, attrayant et utile :

• Nom du projet clair, slogan et proposition de valeur courte.
• Badges uniquement lorsqu'ils sont véridiques et maintenables.
• Démarrage rapide avec des commandes vérifiées lorsque possible.
• Les commandes doivent pouvoir être copiées-collées depuis la racine du dépôt et ne doivent pas contenir les chemins absolus locaux de l'utilisateur actuel ; privilégier ./script.sh, $HOME/..., /chemin/vers/... ou <repo>/... comme exemples.
• Installation, utilisation, configuration, exemples, structure du projet, dépannage et liens vers des fichiers dédiés.
• Ne pas dupliquer le contenu complet de LICENCE, CONTRIBUTING, CHANGELOG ou SECURITY dans le README ; créer des liens vers ces fichiers.
• Préserver les connaissances et exemples existants spécifiques au projet.

Une fois le README.md anglais finalisé, produire une traduction chinoise par défaut :

• Le README.md anglais doit inclure une ligne de commutateur de langue près du haut par défaut, par exemple English | [简体中文](README.zh-CN.md). L'ajouter même lorsque le fichier chinois est encore en cours de génération dans le même passage — le lien pointe vers le chemin qui existera à la fin du workflow.
• Produire le README.zh-CN.md chinois à partir du README.md. La rédaction directe du miroir est préférée pour un README typique (principalement de la prose courte plus du code/commandes qui doivent rester identiques) ; faire appel à la compétence baoyu-translate uniquement lorsque le README est long ou à forte densité terminologique et bénéficie de son flux d'analyse/traduction/révision et d'un glossaire partagé.
• Le README.zh-CN.md chinois porte la ligne de commutateur miroir en haut, par exemple [English](README.md) | 简体中文.
• Conserver tous les blocs de code, commandes, chemins, liens, badges et espaces réservés inchangés ; ne traduire que la prose.
• Ignorer la version chinoise uniquement si l'utilisateur le demande explicitement. Si le projet est déjà principalement rédigé en chinois, traiter README.md comme la version chinoise, traduire en README.en.md, et placer la ligne de commutateur correspondante en haut de chaque fichier.

4. Ajouter les Fichiers Communautaires

Ajouter ou mettre à jour les fichiers uniquement lorsqu'ils aident le projet à paraître complet et digne de confiance :

• LICENSE : utiliser la licence existante si présente ; sinon ajouter MIT par défaut avec l'année courante détectée et le nom du propriétaire/projet le cas échéant.
• CONTRIBUTING.md : configuration de développement, conventions de branche/commit si déductibles, attentes de test, processus d'issue/PR.
• CODE_OF_CONDUCT.md : utiliser un style de pacte de contributeur concis standard sauf si l'utilisateur a une autre politique.
• SECURITY.md : versions supportées, espace réservé pour le canal de divulgation responsable, attentes en matière de signalement de vulnérabilités.
• CHANGELOG.md : initialiser avec Unreleased et la base de référence publique actuelle ; ne pas inventer d'historique de versions.
• SUPPORT.md : où poser des questions, signaler des bugs et demander des fonctionnalités.
• .github/ISSUE_TEMPLATE/* et .github/PULL_REQUEST_TEMPLATE.md : formulaires/listes de contrôle pratiques adaptés au projet.
• CITATION.cff uniquement pour les projets de recherche/académiques/scientifiques ou lorsque les métadonnées de paternité sont disponibles.

5. Hygiène du Dépôt

• Créer ou affiner .gitignore en fonction des langages/outils détectés sans exclure les fichiers qui sont probablement des artefacts sources.
• Ajouter .gitattributes pour la normalisation du texte et les motifs binaires courants lorsque c'est utile.
• Ajouter .editorconfig avec des valeurs par défaut d'espacement conservatrices correspondant au style du dépôt.
• Ne pas ajouter de workflows CI sauf si les commandes de build/test sont connues ou vérifiées ; si ajoutés, les garder minimes et non invasifs.

6. Gestion de Git et du Remote

Pour les dossiers sans Git :

1. Initialiser un dépôt pour le dossier cible après avoir vérifié le chemin du dossier.
2. Stager uniquement les fichiers de métadonnées/documentation créés ou modifiés par ce workflow.
3. Commiter avec un message axé sur la documentation lorsque la publication est en cours.

Pour les dépôts Git sans remote :

1. Déduire le propriétaire GitHub à partir de l'authentification gh et le nom du dépôt à partir du dossier lorsque c'est possible ; ne demander qu'en cas d'ambiguïté.
2. Vérifier l'authentification gh avant de créer un remote.
3. Créer un dépôt GitHub public par défaut.
4. Ajouter origin, définir la branche par défaut, et effectuer un push après avoir examiné les modifications stagées et confirmé qu'aucun secret n'est inclus.

Flux recommandé pour GitHub CLI, adapté au projet :

git status --short
git remote -v
gh auth status
gh repo create PROPRIÉTAIRE/REPO --public --source=. --remote=origin --push

Si les commandes réseau échouent, réessayer une fois avec :

export {HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,http_proxy,https_proxy,all_proxy}=http://127.0.0.1:7890

7. Contrôles Qualité

Avant de finaliser :

• Rouvrir les extraits Markdown modifiés pour vérifier les titres, les liens, les blocs de code et l'indentation des commandes copiables.
• Rechercher dans le README et les documents publics les chemins de machine locaux avant de finaliser, y compris /home/, /Users/, les chemins de lecteur, les noms d'espaces de travail personnels et les chemins absolus copiés depuis l'environnement actuel.
• Confirmer qu'aucun fichier de code source n'a été modifié sauf approbation explicite.
• Confirmer que tous les liens vers des fichiers locaux ciblent des fichiers existants.
• Si un README chinois a été produit, confirmer que README.zh-CN.md existe, que les liens de commutateur de langue se résolvent dans les deux fichiers, et que le code/commandes/chemins restent identiques à la version anglaise.
• Exécuter un formatage léger ou du linting Markdown si disponible ; ne pas installer de dépendances lourdes uniquement pour ce workflow sauf accord de l'utilisateur.
• Afficher git diff --stat et résumer les fichiers modifiés.
• Si un remote a été créé, signaler l'URL, la visibilité, la branche par défaut et si quelque chose a été poussé.

Points de Décision

• README existant de bonne qualité : préserver la structure et compléter les sections manquantes plutôt que de réécrire.
• Aucune commande d'installation/test vérifiée : inclure des espaces réservés clairement marqués ou des notes "pas encore documenté" au lieu d'inventer des commandes.
• Licence inconnue : ajouter MIT par défaut, sauf si l'utilisateur demande une licence différente.
• Possibles secrets ou données privées : arrêter la création/push du remote et signaler les chemins à risque.
• Pas de CLI gh ou non authentifié : fournir les commandes exactes à exécuter par l'utilisateur, mais terminer le polissage local de la documentation et préparer un commit de documentation uniquement si cela est sûr.
• Monorepo : créer ou mettre à jour les fichiers communautaires racine et les README par paquet uniquement lorsque les limites des paquets sont claires.

Résumé de Fin

Terminer par :

• Fichiers ajoutés/mis à jour.
• Ce qui n'a volontairement pas été touché, en particulier le code source.
• Validation effectuée.
• État du dépôt distant, le cas échéant.
• Prochaines étapes suggérées : activer l'IC, ajouter des exemples, faire une première version, ou créer des topics de projet.