Ecrire ses changelogs semi-automatiquement grâce à Git.
Ecrire un changelog, c'est long, c'est fastidieux, bref, c'est chiant, mais lorsque l'on développe un programme que l'on rend publique, c'est un passage obligé pour chaque nouvelle version que l'on publie.
Si votre programme dispose d'un suivi avec Git, il existe une solution pour simplifier cette tâche des plus rébarbatives. Sinon, cela vous donnera peut être une raison de vous mettre à ce formidable outil.
En bonus, si votre programme est disponible librement sur GitHub, vous pouvez y insérer les liens afin que les curieux qui souhaitent en savoir plus puisse aller sur le détail du commit en question.
Dans un terminal, une fois dans le dossier du programme, voici la commande à adapter selon vos besoins.
git log v1...v2 --pretty=format:'* %s [View details](https://github.com/-github-account-/-project-/commit/%H)' --reverse | grep -v Merge > changelogs/v2.md
Regardons la de plus près
- git : commande git, bien évidemment
- log : action permettant à Git de renvoyer la liste des commits
- v1...v2 : différentiel souhaité entre 2 releases, séparé par 3 petits points, ici cela prendra tous les commits effectués entre le tag v1 et le tag v2
- --pretty=format : on indique que l'on souhaite un résultat en sortie formatté
- '* %s [View details](https://github.com/-github-account-/-project-/commit/%H)' : formattage au format markdown où %s indique le sujet du commit et %H sa somme de contrôle.
- --reverse : indique que l'on souhaite l'ordre des commits dans l'ordre chronologique, et par forcément dans l'ordre donnée par Git qui est d'afficher les derniers en premier
- | grep -v Merge : permet de supprimer les merges du log, il est possible de ne par mettre ce paramètre ou de le customiser selon ses besoins
- > changelogs/v2.md : écriture dans un fichier
Ici, l'export se fait au format markdown, mais il est possible d'obtenir du HTML ou n'importe quel autre format, tant que vous arrivez à l'écrire.
Il existe de nombreux paramètres pour personnaliser le formattage, en particulier, il est possible d'ajouter le nom de l'auteur, ou la date, voici une courte liste
- %H : Somme de contrôle du commit
- %h : Somme de contrôle courte du commit
- %an : Nom de l'auteur
- %ae : E-mail de l'auteur
- %ad : Date de création
- %aD : Date de création, format RFC2822
- %ai : Date de création, format ISO 8601
- %cn : Nom du validateur
- %ce : E-mail du validateur
- %cd : Date de validatation
- %cD : Date de validatation, format RFC2822
- %ci : Date de validatation, format ISO 8601
Une liste plus complète peut être consultée sur cette page.
Une fois le fichier créé, il est toujours possible de le modifier pour ajouter titres, dates, bref tout ce que vous avez besoin de renseigner pour compléter votre changelog.