mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Create 1.0.0 version for French
This commit is contained in:
Olivier Lacan
parent
90f7d93061
commit
23c700d538
317
source/fr/1.0.0/index.html.haml
Normal file
317
source/fr/1.0.0/index.html.haml
Normal file
@ -0,0 +1,317 @@
|
||||
---
|
||||
description: Tenez un Changelog
|
||||
title: Tenez un Changelog
|
||||
language: fr
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
||||
- gemnasium = "https://gemnasium.com/"
|
||||
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
||||
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
||||
- semver = "http://semver.org/"
|
||||
- shields = "http://shields.io/"
|
||||
- thechangelog = "http://5by5.tv/changelog/127"
|
||||
- vandamme = "https://github.com/tech-angels/vandamme/"
|
||||
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
|
||||
- ghr = "https://help.github.com/articles/creating-releases/"
|
||||
|
||||
.header
|
||||
.title
|
||||
%h1 Tenez un Changelog
|
||||
%h2 Ne laissez pas vos amis utiliser les logs git comme changelogs
|
||||
|
||||
= link_to changelog do
|
||||
Version
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Qu'est-ce qu'un changelog ?
|
||||
|
||||
%p
|
||||
Un changelog (journal de modifications) est un fichier qui contient
|
||||
une liste triée chronologiquement des changements notables pour
|
||||
chaque version d’un projet
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Pourquoi tenir un changelog ?
|
||||
|
||||
%p
|
||||
Pour permettre aux utilisateurs et contributeurs de voir précisement
|
||||
quel changements notables ont été faits entre chaque publication
|
||||
(ou version) d'un projet.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Qui a besoin d'un changelog ?
|
||||
|
||||
%p
|
||||
Tout le monde. Qu'ils soient consomateurs ou developeurs, 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ême personnes veulent savoir comment et pourquoi.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
Comment créer un bon changelog ?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Principes Directeurs
|
||||
|
||||
%ul
|
||||
%li
|
||||
Les changelogs sont <em>pour les êtres humains</em>, pas les machines.
|
||||
%li
|
||||
Il doit il y avoir une section pour chaque version.
|
||||
%li
|
||||
Les changements similaires doivent être groupés.
|
||||
%li
|
||||
Les versions et sections doivent être liables.
|
||||
%li
|
||||
La version la plus récente se situe en haut du fichier.
|
||||
%li
|
||||
La date de publication de chaque version est indiquée.
|
||||
%li
|
||||
Indiquer si le projet respecte le #{link_to "Versionnage Sémantique", semver}.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Types de changements
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
pour les nouvelles fonctionnalités.
|
||||
%li
|
||||
%code Changed
|
||||
pour les changements aux fonctionnalités préexistantes.
|
||||
%li
|
||||
%code Deprecated
|
||||
pour les fonctionnalités qui seront bientôt supprimées.
|
||||
%li
|
||||
%code Removed
|
||||
pour les fonctionnalités désormais supprimées.
|
||||
%li
|
||||
%code Fixed
|
||||
pour les corrections de bugs.
|
||||
%li
|
||||
%code Security
|
||||
en cas de vulnerabilités.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
Comment puis-je minimiser le travail nécessaire pour maintenir un changelog ?
|
||||
|
||||
%p
|
||||
Gardez une section <code>Unreleased</code> en haut du fichier afin de lister
|
||||
tous les changements qui n'ont pas encore été publiés.
|
||||
|
||||
%p Cela rempli deux objectifs:
|
||||
|
||||
%ul
|
||||
%li
|
||||
Les gens peuvent voir les changements auxquels ils peuvent s’attendrent
|
||||
dans les prochaines publications.
|
||||
%li
|
||||
Au moment de la publication, vous pouvez déplacer les changements listés
|
||||
dans la section <code>Unreleased</code> dans la section d'une nouvelle
|
||||
version.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Est-ce que les changelogs peuvent être mauvais ?
|
||||
|
||||
%p Oui. Voici quelques exemples de changelogs plutôt inutiles.
|
||||
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Diffs de journaux git
|
||||
|
||||
%p
|
||||
Utiliser des diffs de journaux git en tant que changelogs est une mauvaise
|
||||
idée: ils sont remplis de bruit. Les journaux git sont remplis de choses
|
||||
comme des commits de merge, des commits avec des titres obscures, des
|
||||
changements concernant la documentation, etc.
|
||||
|
||||
%p
|
||||
Le but d'un commit est de documenter une étape dans l'évolution du code
|
||||
source. Certains projets nettoient leurs commits, d'autres non.
|
||||
|
||||
%p
|
||||
Le but d'une section de changelog est de documenter la difference notable
|
||||
entre deux versions, souvent à travers de multiples commits, afin de la
|
||||
communiquer clairement aux utilisateurs.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Ignorer les dépréciations
|
||||
|
||||
%p
|
||||
Lorsque l'on passe d'une version d'un logiciel à une autre, il devrait être
|
||||
très clair si quelque chose peut ne pas 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.
|
||||
|
||||
%p
|
||||
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.
|
||||
|
||||
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Dates confuses
|
||||
|
||||
%p
|
||||
Aux États-Unis, les gens mettent le mois en premier (<code>06-02-2012</code>
|
||||
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. <code>2012-06-02</code> fonctionne logiquement, du plus grand
|
||||
au plus petit, ne laisse pas place à la confusion avec un autre format et
|
||||
est un #{link_to "standard ISO", iso}. C'est pour cela que ce format de date
|
||||
est recommandé pour les change logs.
|
||||
|
||||
%aside
|
||||
Il y en a d’autres. Aidez-moi à collecter ces anti-patrons en
|
||||
#{link_to "ouvrant une issue", "#issues"} ou une pull request.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Questions fréquemment posées
|
||||
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Y a-t-il un format de changelog standard ?
|
||||
|
||||
%p
|
||||
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
|
||||
resources sont inappropriées et insuffisantes.
|
||||
|
||||
%p
|
||||
Ce projet vise à devenir
|
||||
= link_to "une meilleure convention pour les changelogs.", changelog
|
||||
Il a pour origine l'observation et le rassemblement des bonne pratiques dans
|
||||
la communauté open source.
|
||||
|
||||
%p
|
||||
Les critiques constructives, discussions et suggestions pour améliorer ce
|
||||
projet #{link_to "sont les bienvenues.", issues}.
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
Comment doit-être nommé le fichier de change log ?
|
||||
|
||||
%p
|
||||
Nommez le <code>CHANGELOG.md</code>. Certains projects utilisent
|
||||
<code>HISTORY</code>, <code>NEWS</code> ou <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
Même s'il est facile d'imaginer que le nom d'un fichier de changelog n'a
|
||||
pas grant interêt, pourquoi rendre la tâche difficile que nécessaire pour
|
||||
les utilisateurs qui cherchent à trouver les changements notables de votre
|
||||
projet ?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
Quid de GitHub Releases ?
|
||||
|
||||
%p
|
||||
C'est une excellente initiative. #{link_to "Releases", ghr} peut être
|
||||
utilisé pour transformer de simples tags git (par exemple un tag nommé
|
||||
<code>v1.0.0</code>) 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.
|
||||
|
||||
%p
|
||||
GitHub Releases crée un changelog non-portable qui n'est visible par les
|
||||
utilisateurs qu'à l'interieur du context de GitHub. Il est possible de
|
||||
suivre le même format que Keep a Changelog, mais c'est plus difficile.
|
||||
|
||||
%p
|
||||
La version actuelle de GitHub Releases est également difficile à découvrir
|
||||
pour les utilisateurs, contrairement aux fichiers en majuscules typiques
|
||||
(<code>README</code>, <code>CONTRIBUTING</code>, etc.). Un autre soucis
|
||||
mineur est que l'interface ne permet pas actuellement d'offrir des liens
|
||||
vers les journaux git entre chaque publication.
|
||||
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Les change logs peuvent-ils être parsés automatiquement ?
|
||||
|
||||
%p
|
||||
C'est difficile, parce que les gens suivent des formats et utilisent des noms
|
||||
de fichiers très différents.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} est une Ruby gem créée par l'équipe
|
||||
#{link_to "Gemnasium", gemnasium} qui parse les change logs de
|
||||
beaucoup (mais pas tous) de projets open source.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
Qu'en est-il des publications "yanked" (retirées) ?
|
||||
|
||||
%p
|
||||
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:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
Le tag <code>[YANKED]</code> 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.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Devriez-vous réécrire un changelog ?
|
||||
|
||||
%p
|
||||
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.
|
||||
|
||||
%p
|
||||
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.
|
||||
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
Comment puis-je contribuer ?
|
||||
|
||||
%p
|
||||
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.
|
||||
|
||||
%p
|
||||
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.
|
||||
|
||||
%p
|
||||
Donc s'il vous plaît, <strong>#{link_to "participez", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Conversations
|
||||
%p
|
||||
J'ai participé au podcast #{link_to "The Changelog", thechangelog}
|
||||
pour explique pourquoi les mainteneurs et les contributeurs devraient se
|
||||
soucier des changelogs et également des motivations derrière ce projet.
|
||||
Loading…
x
Reference in New Issue
Block a user