Rédiger un changelog, à partir de vos commits

Remplissez un court formulaire et obtenez un README.md net avec étapes d'installation, utilisation, configuration et licence, ou un CHANGELOG.md au format Keep a Changelog. Voyez le résultat au fil de la frappe. Tout est écrit dans votre navigateur, et rien de ce que vous saisissez n'est envoyé. C'est gratuit.

Comment créer un README, étape par étape

1. Choisissez README.md en haut.
2. Sous À propos du projet, saisissez le Nom du projet, un Résumé en une ligne, une Description, ainsi que les Fonctionnalités et les Prérequis, un par ligne.
3. Sous Installation et utilisation, choisissez un Gestionnaire de paquets comme npm, pip ou Cargo, ajoutez l'URL du dépôt et écrivez votre Utilisation. Choisissez le langage d'utilisation pour que le code soit correctement mis en forme.
4. Ajoutez des commandes de Configuration et de Développement si elles s'appliquent.
5. Choisissez une Licence et un Titulaire du copyright, et activez la Table des matières, le Badge de licence ou la section Contribuer selon les besoins.
6. Appuyez sur Copier le Markdown ou Télécharger README.md.

Ce qui fait un bon README

Dites en une ligne ce que fait le projet, puis montrez comment l'installer et le plus petit exemple qui fonctionne. Les lecteurs décident en quelques secondes si un projet leur convient : les fonctionnalités et prérequis viennent donc ensuite, suivis des réglages, des commandes de développement, de la façon de contribuer et de la licence. Les sections laissées vides sont omises.

Des changelogs lisibles

Le changelog suit Keep a Changelog : version la plus récente en premier, chacune avec une date et ses changements regroupés en Ajouté, Modifié, Déprécié, Supprimé, Corrigé et Sécurité. Gardez une section Non publié en haut pour les changements qui ne sont pas encore sortis. Avec une adresse de dépôt, chaque version renvoie à la comparaison avec la précédente. Vous pouvez ajouter une version plus ancienne à la main, ou construire des entrées à partir des messages de commit.

Conseils

• Mettez une commande d'installation qui fonctionne et un court exemple d'utilisation près du haut.
• Nommez clairement la licence pour que les autres sachent comment ils peuvent utiliser votre code.
• Gardez la description centrée sur ce que fait le projet pour le lecteur, pas sur la façon dont vous l'avez construit.
• Mettez à jour le changelog à chaque version, pas seulement à la fin.

Pour garder secrets et fichiers de build hors d'un dépôt, utilisez le générateur de .gitignore et le générateur de .env.example.

Questions

Puis-je partir de mon historique de commits ?

Oui. Collez la sortie de git log --oneline sous À partir des messages de commit. Les commits écrits sous la forme feat:, fix:, perf: et ainsi de suite sont classés dans les bons groupes, et les changements majeurs marqués d'un point d'exclamation sont signalés. Retouchez ensuite la formulation ; les messages de commit s'écrivent pour les développeurs, les changelogs pour les utilisateurs.

Ajoute-t-il le texte de la licence ?

Il ajoute une section Licence qui nomme la licence et renvoie à un fichier LICENSE. Mettez le texte complet de la licence dans ce fichier ; la page officielle de la licence le fournit.

Où vont les fichiers ?

Télécharger enregistre README.md ou CHANGELOG.md sur votre appareil. Placez-le à la racine de votre dépôt et les hébergeurs de code l'afficheront sur la page du projet.

Quelles licences puis-je choisir ?

MIT, Apache 2.0, GPL 3.0, BSD 3-Clause, ISC, MPL 2.0, Unlicense ou Tous droits réservés, ou laissez la section de côté.