Tenez un Changelog

Ne laissez pas vos amis utiliser les logs git comme changelogs

Version 1.0.0
# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2017-06-20
### Added
- New visual identity by @tylerfortune8.
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from @tianshuo.
- German translation from @mpbzh & @Art4.
- Italian translation from @azkidenz.
- Swedish translation from @magol.
- Turkish translation from @karalamalar.
- French translation from @zapashcanon.
- Brazilian Portugese translation from @aisamu.
- Polish translation from @amielucha.
- Russian translation from @aishek.
- Czech translation from @h4vry.
- Slovak translation from @jkostolansky.

### Changed
- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
  scenario.
- Improve "Commit log diffs" sub-section to further argument against
  them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs"
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portugese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed
- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03
### Added
- RU translation from @aishek.
- pt-BR translation from @tallesl.
- es-ES translation from @ZeliosAriex.

## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can
benefit both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06
### Added
- Answer "Should you ever rewrite a change log?".

### Changed
- Improve argument against commit logs.
- Start following [SemVer](http://semver.org) properly.

## [0.0.8] - 2015-02-17
### Changed
- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
  writes dates in a strange way.

### Fixed
- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16
### Added
- Link, and make it obvious that date format is ISO 8601.

### Changed
- Clarified the section on "Is there a standard change log format?".

### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12
### Added
- README section on "yanked" releases.

## [0.0.5] - 2014-08-09
### Added
- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
keeping prior to releases.

## [0.0.4] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG")
and its function "the change log".

### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
to differentiate between the file and the purpose of the file — the
logging of changes.

### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and
create too much noise in the file. People will have to assume that the
missing sections were intentionally left out because they contained no
notable changes.

## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.

## 0.0.1 - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example of a
  standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain
- README now contains answers to common questions about CHANGELOGs
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?"

[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2

Qu'est-ce qu'un changelog ?

Un changelog (journal des modifications) est un fichier qui contient une liste triée chronologiquement des changements notables pour chaque version d’un projet

Pourquoi tenir un changelog ?

Pour permettre aux utilisateurs et contributeurs de voir précisément quels changements notables ont été faits entre chaque publication (ou version) d'un projet.

Qui a besoin d'un changelog ?

Tout le monde. Qu'ils soient consommateurs ou développeurs, les utilisateurs de logiciels sont des êtres humains qui se soucient de connaître le contenu des logiciels qu'ils utilisent. Quand un logiciel change, ces mêmes personnes veulent savoir comment et pourquoi.

Comment créer un bon changelog ?

Principes Directeurs

  • Les changelogs sont pour les êtres humains, pas les machines.
  • Il doit y avoir une section pour chaque version.
  • Les changements similaires doivent être groupés.
  • Les versions et sections doivent être liables.
  • La version la plus récente se situe en haut du fichier.
  • La date de publication de chaque version est indiquée.
  • Indiquer si le projet respecte le Versionnage Sémantique.

Types de changements

  • Added pour les nouvelles fonctionnalités.
  • Changed pour les changements aux fonctionnalités préexistantes.
  • Deprecated pour les fonctionnalités qui seront bientôt supprimées.
  • Removed pour les fonctionnalités désormais supprimées.
  • Fixed pour les corrections de bugs.
  • Security en cas de vulnérabilités.

Comment puis-je minimiser le travail nécessaire pour maintenir un changelog ?

Gardez une section Unreleased en haut du fichier afin de lister tous les changements qui n'ont pas encore été publiés.

Cela permet deux choses:

  • Les gens peuvent voir les changements auxquels ils peuvent s’attendre dans les prochaines publications.
  • Au moment de la publication, vous pouvez déplacer les changements listés dans la section Unreleased dans la section d'une nouvelle version.

Est-ce que les changelogs peuvent être mauvais ?

Oui. Voici quelques exemples de changelogs plutôt inutiles.

Diffs de journaux gits

Utiliser des diffs de journaux gits en tant que changelogs est une mauvaise idée: ils sont remplis de bruit. Les journaux gits sont remplis de choses comme des commits de merge, des commits avec des titres obscurs, des changements concernant la documentation, etc.

Le but d'un commit est de documenter une étape dans l'évolution du code source. Certains projets nettoient leurs commits, d'autres non.

Le but d'une section de changelog est de documenter les différences notables entre deux versions, souvent à travers de multiples commits, afin de les communiquer clairement aux utilisateurs.

Ignorer les dépréciations

Lorsque l'on passe d'une version d'un logiciel à une autre, il devrait être très clair si quelque chose peut ne plus fonctionner. Il devrait être possible de mettre à jour vers un version qui offre une liste des fonctionnalités dépréciées, de retirer ce qui est déprécié, puis de mettre à jour vers la version où les dépréciations deviennent des suppressions de fonctionnalités.

Si vous ne faites rien d'autre, listez les dépréciations, les supressions de fonctionnalités, et tous les changements non rétrocompatibles dans votre changelog.

Dates confuses

Aux États-Unis, les gens mettent le mois en premier (06-02-2012 pour le 2 Juin 2012), tandis que beaucoup de gens dans le reste du monde l’écrivent de la façon robotique suivante "2 Juin 2012", alors qu’ils le prononcent différement. 2012-06-02 fonctionne logiquement, du plus grand au plus petit, ne laisse pas place à la confusion avec un autre format et est un standard ISO. C'est pour cela que ce format de date est recommandé pour les changelogs.

Questions fréquemment posées

Y a-t-il un format de changelog standard ?

Pas vraiment. Il y a le guide de style GNU pour les changelogs, ou les instructions GNU de deux paragraphes pour les fichiers NEWS. Ces deux ressources sont inappropriées et insuffisantes.

Ce projet vise à devenir une meilleure convention pour les changelogs. Il a pour origine l'observation et le rassemblement des bonne pratiques dans la communauté open source.

Les critiques constructives, discussions et suggestions pour améliorer ce projet sont les bienvenues..

Comment doit-être nommé le fichier de changelog ?

Nommez-le CHANGELOG.md. Certains projets utilisent HISTORY, NEWS ou RELEASES.

Même s'il est facile d'imaginer que le nom d'un fichier de changelog n'a pas grand intérêt, pourquoi rendre la tâche plus difficile que nécessaire aux utilisateurs qui cherchent à trouver les changements notables de votre projet ?

Quid de GitHub Releases ?

C'est une excellente initiative. Releases peut être utilisé pour transformer de simples tags git (par exemple un tag nommé v1.0.0) en notes de publication riches soit en ajoutant manuellement des notes soit en utilisant les messages de tags gits annotés et en les transformant en notes.

GitHub Releases crée un changelog non-portable qui n'est visible par les utilisateurs qu'à l'intérieur du contexte de GitHub. Il est possible de suivre le même format que Keep a Changelog, mais c'est plus difficile.

La version actuelle de GitHub Releases est également difficile à découvrir pour les utilisateurs, contrairement aux fichiers en majuscules typiques (README, CONTRIBUTING, etc.). Un autre souci mineur est que l'interface n'offre actuellement pas de lien vers les journaux gits entre chaque publication.

Les changelogs peuvent-ils être parsés automatiquement ?

C'est difficile, parce que les gens suivent des formats et utilisent des noms de fichiers très différents.

Vandamme est une Ruby gem créée par l'équipe Gemnasium qui parse les changelogs de beaucoup (mais pas tous) de projets open source.

Qu'en est-il des publications "yanked" (retirées) ?

Les publications yanked sont des version qui ont dû être retirées du fait d'un sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent même pas dans les changelogs. Elles devraient. Voilà comment les afficher:

## 0.0.5 - 2014-12-13 [YANKED]

Le tag [YANKED] n'est pas mis en avant pour rien. Il est important qu'il soit remarqué. Il est également plus facile à digérer pour un programme puisqu'il est entouré par des crochets.

Devriez-vous réécrire un changelog ?

Bien sûr. Il y a toujours de bonnes raisons d'améliorer un changelog. J'ouvre souvent des pull requests pour ajouter des publications manquantes sur des projets open source avec des changelogs non-maintenus.

Il est aussi possible que vous découvriez que vous aviez oublié de mentionner un changement majeur dans les notes de version. Il est évidemment important que vous mettiez votre changelog à jour dans ce cas.

Comment puis-je contribuer ?

Ce document n'est pas la **vérité**; c'est mon opinion soigneusement réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés.

C'est parce que je veux que notre communauté atteigne un consensus. Je crois que la discussion est aussi importante que le résultat final.

Donc s'il vous plaît, participez.

Conversations

J'ai participé au podcast The Changelog pour expliquer pourquoi les mainteneurs et contributeurs doivent se soucier des changelogs et également des motivations derrière ce projet.