Tenez un Changelog

Ne laissez pas vos amis utiliser les logs git comme changelogs

Version 1.1.0
# Changelog

All notable changes to this project will be documented in this file.

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

## [Unreleased]

### Added

- v1.1 Brazilian Portuguese translation.
- v1.1 German Translation
- v1.1 Spanish translation.
- v1.1 Italian translation.
- v1.1 Polish translation.
- v1.1 Ukrainian translation.

### Changed

- Use frontmatter title & description in each language version template
- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
  image that will render properly (although in English for all languages)
- Fix OpenGraph title & description for all languages so the title and 
description when links are shared are language-appropriate

### Removed

- Trademark sign previously shown after the project description in version 

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).
- v1.1 French translation.
- v1.1 Dutch translation (#371).
- v1.1 Russian translation (#410).
- v1.1 Japanese translation (#363).
- v1.1 Norwegian Bokmål translation (#383).
- v1.1 "Inconsistent Changes" Turkish translation (#347).
- Default to most recent versions available for each languages.
- Display count of available translations (26 to date!).
- Centralize all links into `/data/links.json` so they can be updated easily.

### Fixed

- Improve French translation (#377).
- Improve id-ID translation (#416).
- Improve Persian translation (#457).
- Improve Russian translation (#408).
- Improve Swedish title (#419).
- Improve zh-CN translation (#359).
- Improve French translation (#357).
- Improve zh-TW translation (#360, #355).
- Improve Spanish (es-ES) transltion (#362).
- Foldout menu in Dutch translation (#371).
- Missing periods at the end of each change (#451).
- Fix missing logo in 1.1 pages.
- Display notice when translation isn't for most recent version.
- Various broken links, page versions, and indentations.

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

- Unused normalize.css file.
- Identical links assigned in each translation file.
- Duplicate index file for the english version.

## [1.1.0] - 2019-02-15

### Added

- Danish translation (#297).
- Georgian translation from (#337).
- Changelog inconsistency section in Bad Practices.

### Fixed

- Italian translation (#332).
- Indonesian translation (#336).

## [1.0.0] - 2017-06-20

### Added

- New visual identity by [@tylerfortune8](https://github.com/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](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@emreerkan](https://github.com/emreerkan).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).

### 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
- Improve "Commit log diffs" sub-section to further argument against
- Merge "Why can’t people just use a git log diff?" with "Commit log
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese 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](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/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](https://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.1.1...HEAD
[1.1.1]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0
[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
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1

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 une 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.

Inconsistent Changes

Un changelog qui ne mentionne qu'une portion des changements peut être aussi dangereux que l'absence totale de changelog. Bien que la majorité des changements peuvent être sans conséquence, par exemple retirer un simple espace dans un texte ne nécessite probablement pas de mention, tout changements important devrait être mentionné dans le changelog. Sans consistence dans l'application des changements, vos utilisateurs pourraient être induit en erreur et penser que le changelog est la seule source de d'information. Ça devrait être le cas. Son pouvoir implique des responsabilités: un bon changelog est synonyme avec un changelog mis à jour de façon consistante.

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.


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.