cleobnvntra / Genereadme

GENEREADME est un outil de ligne de commande qui récupère un fichier de code source et génère un fichier README.md qui explique le code du fichier à l'aide d'un LLM.

Contributions

Les contributions à GENEREADME sont les bienvenues ! Veuillez consulter CONTRIBUTING.md pour obtenir des directives sur la configuration de l'environnement, comment exécuter et tester l'outil et soumettre des modifications.

GENEREADME

GENEREADME est un outil de ligne de commande qui récupère un fichier, le traite et génère un fichier README avec une explication ou une documentation du contenu du fichier. L'outil utilise la complétion du chat OpenAI pour analyser le fichier et générer du contenu.

Releasing GENEREADME

Utilisation

Installez l'outil en exécutant la commande suivante :

npm i -g genereadme

Copier après la connexion

L'outil prend actuellement en charge Groq et OpenRouter, qui utilise Groq par défaut. Une clé API valide pour le fournisseur approprié doit être fournie.

Fournissez une clé API valide soit en créant un fichier .env, soit via l'indicateur -a ou --api-key lors de l'utilisation de la commande :

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Copier après la connexion

Exécutez l'outil avec les exemples de fichiers existants ou commencez à utiliser les vôtres :

…

Voir sur GitHub

Le processus

La publication de l'outil lui-même n'a posé aucun problème, cependant, j'ai dû suivre quelques étapes supplémentaires pour garantir une version appropriée.

Recherche

Avant de me concentrer sur le processus de publication, j'ai pris le temps de rechercher les meilleures pratiques et les étapes de publication d'un package dans le registre npm. Voici ce que j'ai appris :

1. Comment publier un package sur npm
Pour comprendre le processus de base, j'ai fait référence à la documentation officielle de npm. Ce guide a fourni un aperçu des étapes essentielles, notamment la configuration d'un package.json, l'exécution de npm submit et la gestion des versions.

2. Utilisation du versioning sémantique
La gestion des versions joue un rôle crucial dans la signalisation des modifications aux utilisateurs. J'ai examiné les principes du versioning sémantique, qui utilise le format MAJOR.MINOR.PATCH pour décrire les modifications majeures, les nouvelles fonctionnalités et les corrections de bogues. Cela garantissait que mon outil aurait un numéro de version significatif pour chaque version.

3. Gestion de .npmignore
J'ai recherché comment utiliser efficacement le fichier .npmignore pour garantir que mon package npm inclut uniquement les fichiers nécessaires aux utilisateurs finaux. En créant soigneusement ce fichier, j'ai pu exclure les fichiers spécifiques au développement tels que les fichiers de configuration, les tests et la documentation qui ne sont pas requis dans le package publié. Cela a non seulement réduit la taille du package, mais l'a également rendu plus professionnel en se concentrant uniquement sur ce dont les utilisateurs ont réellement besoin pour exécuter l'outil. Gérer correctement .npmignore est une étape critique dans la préparation d’une version soignée.

Libérer

Après avoir fait mes recherches, j'ai vérifié toutes les exigences, tous les bugs possibles et tous les tests ayant échoué.
Une fois que tout me paraissait bien, j'ai procédé à la publication du package en exécutant :

npm i -g genereadme

Copier après la connexion

REMARQUE : L'exécution de cette commande nécessitera que l'utilisateur soit connecté à son compte npm en exécutant la commande :

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Copier après la connexion

Essai

Maintenant que j'ai publié la v1.0.0 de GENEREADME, il était temps de demander à certains utilisateurs finaux de tester si le package fonctionne.
Comme prévu, quelques bugs ont été corrigés. Celui qui n’affecte pas les performances de l’outil, et celui qui le casse réellement.

Ajustement

Bogue de la commande de version

Le bug simple qui a été trouvé concerne l'utilisation de la commande genereadme -v. Cette commande doit imprimer le nom de l'outil et la version actuelle. Cependant, la façon dont j'ai codé cette partie est que je récupère le nom et la version du projet à partir du package.json dans le répertoire actuel. Cela signifie que si un utilisateur final exécute cette commande, il affichera le nom et la version de LEUR projet au lieu du mien. Il s'agissait donc d'une solution simple pour s'assurer simplement qu'il le récupérera toujours à partir du bon projet.

Bug du répertoire de sorties

Maintenant, celui-ci est un bug qui casse l'outil qui fonctionnait techniquement lors de mes tests locaux, mais j'ai oublié un simple cas de test.
La structure des dossiers du projet n'avait en tête que les développeurs et les contributeurs, il est donc attendu d'avoir le dossier de sorties dans le projet, que j'ai également poussé vers le dépôt principal contenant un exemple de résultat d'une sortie.

Maintenant, je devais garder à l'esprit que ce sera légèrement différent pour l'utilisateur final.
Auparavant, le code était écrit pour simplement écrire dans le répertoire outputs/ sans vérifier son existence, et pour en créer un si ce n'était pas le cas. Cela a provoqué l'échec des tests manuels du package publié puisque l'utilisateur final n'avait pas de répertoire outputs/, l'outil échouera simplement au lieu d'en créer un s'il n'existe pas.

Après cette découverte, j'ai pensé assez simple, non ?
Jusqu'à ce que j'essaye de pousser les changements en pensant "D'accord, ça répare le problème !" mais à ma grande surprise, mon CI a échoué !

Le coupable :

npm i -g genereadme

Copier après la connexion

Voici donc comment je vérifie et crée le répertoire outputs/. Cependant, lors de mes tests de bout en bout, je me moquais de fs.existsSync() pour renvoyer une valeur false pour cette raison :

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Copier après la connexion

Cette fonction recherche un fichier de configuration toml qui utilise fs.existsSync(), et je ne voulais pas utiliser de fichier de configuration toml pour mes tests de bout en bout, je me suis moqué de cette méthode pour renvoyer false, ce qui est maintenant en conflit avec la correction de bug que j'ai effectuée.

Je n'ai pas encore maîtrisé le moqueur et découvert des moyens de créer éventuellement différentes valeurs fictives pour la même méthode et dans différentes conditions. Donc, jusqu'à ce que j'apprenne cette procédure, j'ai apporté le correctif temporaire pour garantir que le répertoire outputs/ soit supprimé avant chaque scénario de test.