Chapitre 518 minDébutant
README et CHANGELOG : écrire et versionner
Par Josselyn C., prof de BTS SIO. Mis à jour le .
À la fin de ce chapitre, tu sauras
- écrire un README qui permet d'installer et de lancer un projet ;
- tenir un CHANGELOG au format Keep a Changelog ;
- choisir le prochain numéro de version avec SemVer ;
- distinguer CHANGELOG, historique Git et notes de version.
4 exercices corrigés
Le README est le fichier d'accueil d'un projet, placé à la racine du dépôt : il dit à quoi sert le projet et comment l'installer, le lancer et le tester. Le CHANGELOG liste, version par version, les changements notables, pour ceux qui mettent à jour ou utilisent le logiciel. Ce chapitre donne le contenu d'un bon README, un exemple complet, le format Keep a Changelog et la façon de numéroter les versions avec le versionnage sémantique.
Le README, porte d'entrée du projet
Sur GitHub ou GitLab, le fichier README.md s'affiche sous la liste des fichiers : c'est la première chose que lit un développeur qui découvre le dépôt, et la première chose que lit la commission de l'E6 qui ouvre le tien. Son objectif tient en une phrase : quelqu'un qui ne connaît pas le projet le fait tourner sur son poste en un quart d'heure, sans t'appeler.
Pour y arriver, le README répond, dans l'ordre, aux questions du nouveau venu :
| Rubrique | Question à laquelle elle répond | Erreur fréquente |
|---|---|---|
| Titre et description | C'est quoi, pour qui, pour quoi faire ? | Une description technique sans le besoin métier |
| Fonctionnalités | Que sait faire le projet aujourd'hui ? | Lister des fonctions prévues mais pas faites |
| Prérequis | Que dois-je installer avant, en quelle version ? | « Node.js » sans version |
| Installation | Quelles commandes, dans quel ordre ? | Une étape oubliée parce qu'elle était déjà faite chez toi |
| Configuration | Quelles variables, quel fichier ? | Un vrai mot de passe dans le README |
| Lancement et tests | Comment je vois que ça marche ? | Pas de commande de test |
| Comptes de démonstration | Avec quel compte je me connecte ? | Des comptes réels, ou aucun compte |
| Documentation | Où est le reste (API, architecture, guide utilisateur) ? | Tout mettre dans le README |
| Licence, auteurs, contact | Ai-je le droit de l'utiliser, à qui m'adresser ? | Pas de licence, donc aucun droit d'utilisation |
Un README complet
Voici le README de l'API du parc de Sorbier, l'application dont le chapitre 8 documente les routes. Chaque rubrique est courte, et chaque commande a été testée telle qu'elle est écrite.
# API du parc
API REST interne du service informatique de Sorbier Logistique : inventaire
des postes de travail et ouverture de tickets d'assistance depuis l'intranet.
Version actuelle : voir [CHANGELOG.md](CHANGELOG.md).
## Fonctionnalités
- Consulter l'inventaire des postes, filtré par type ou par disponibilité.
- Ouvrir un ticket d'assistance au nom de l'utilisateur connecté.
- Authentification par jeton JWT délivré par l'intranet.
## Prérequis
- Node.js 24 LTS et npm
- MySQL 8.4 avec la base `parc` ([script de création](docs/sql/parc.sql))
- Git
## Installation
```bash
git clone https://github.com/sorbier-logistique/api-parc.git
cd api-parc
npm ci
cp .env.example .env
```
Renseigne ensuite les variables du fichier `.env` (tableau ci-dessous).
## Configuration
| Variable | Rôle | Exemple |
|---|---|---|
| `PORT` | Port d'écoute de l'API | `3000` |
| `DB_HOST` | Serveur MySQL | `localhost` |
| `DB_NAME` | Nom de la base | `parc` |
| `DB_USER` | Compte applicatif, droits limités | `api_parc` |
| `DB_PASSWORD` | Mot de passe du compte applicatif | à demander au service informatique |
| `JWT_PUBLIC_KEY` | Clé publique qui vérifie les jetons | chemin vers le fichier `.pem` |
Le fichier `.env` n'est jamais commité (il est dans `.gitignore`).
## Lancer et tester
```bash
npm run dev # lance l'API sur http://localhost:3000
npm test # lance les tests automatisés
```
La documentation interactive de l'API est servie sur `http://localhost:3000/docs`
en développement uniquement.
## Documentation
- [Documentation de l'API (OpenAPI)](docs/api/openapi.yaml)
- [Architecture et choix techniques](docs/architecture.md)
- [Procédure de déploiement](docs/exploitation/deploiement.md)
## Licence et contact
Code propriété de Sorbier Logistique, usage interne.
Contact : service informatique, informatique@sorbier.example.
Quatre détails font la différence. La version n'est pas recopiée dans le README (elle serait vite fausse) : il renvoie au CHANGELOG. Les prérequis donnent les versions. npm ci installe exactement les versions du fichier package-lock.json, ce qui garantit la même installation chez tout le monde. Et le mot de passe de la base n'apparaît nulle part : le tableau dit où l'obtenir.
Le README d'un dépôt d'infrastructure
Un dépôt de scripts d'administration ou de configurations a autant besoin d'un README qu'une application. Le lecteur est un administrateur qui veut savoir ce que fait chaque script, où il tourne et ce qu'il risque de casser.
| Rubrique | Exemple pour le dépôt sorbier-scripts |
|---|---|
| Rôle du dépôt | Scripts d'administration du siège : création de comptes, sauvegardes, rapports |
| Inventaire des scripts | Un tableau : script, rôle, serveur d'exécution, planification, journal produit |
| Prérequis | PowerShell 7 sur le poste d'administration ; module ActiveDirectory ; accès au bastion |
| Utilisation | Une commande d'exemple par script, avec ses paramètres |
| Sécurité | Aucun mot de passe dans le dépôt ; les secrets viennent du coffre-fort de l'équipe |
| Tests | Comment essayer un script sans risque (paramètre -WhatIf, VM de recette) |
Le CHANGELOG
Un CHANGELOG (journal des modifications) est un fichier, CHANGELOG.md à la racine du dépôt, qui liste pour chaque version les changements notables, écrits pour des humains. Il répond à la question de celui qui doit mettre à jour : qu'est-ce qui a changé, et est-ce que ça me concerne ?
Le format le plus répandu est Keep a Changelog, dont la version 2.0.0 a été publiée le 7 juin 2026. Elle change les conseils autour du fichier mais pas le format lui-même : un CHANGELOG écrit selon la version 1.1 reste valable. Ses principes :
- un CHANGELOG est fait pour les humains, pas pour les machines ;
- chaque version a son entrée, la plus récente en haut ;
- chaque version porte sa date au format
AAAA-MM-JJ, qui évite toute confusion entre jour et mois ; - les changements du même type sont regroupés sous six rubriques, ni plus ni moins ;
- une section Non publié (Unreleased) en haut accumule les changements à venir ; au moment de livrer, elle devient la nouvelle version, datée, et une section vide la remplace ;
- le fichier dit quelle numérotation il suit, le plus souvent le versionnage sémantique ;
- on écrit des phrases claires et courtes : beaucoup de lecteurs ne lisent pas dans leur langue maternelle.
| Rubrique (Keep a Changelog) | En français | Pour |
|---|---|---|
| Added | Ajouté | Les nouvelles fonctionnalités |
| Changed | Modifié | Les changements d'une fonctionnalité existante |
| Deprecated | Obsolète | Ce qui sera bientôt supprimé |
| Removed | Supprimé | Ce qui a été supprimé |
| Fixed | Corrigé | Les corrections de bugs |
| Security | Sécurité | Les corrections de vulnérabilités |
Les rubriques officielles sont en anglais ; une équipe française peut les traduire, à condition de garder les mêmes six termes partout, comme les cours de ce site. Voici le CHANGELOG de l'API du parc :
# Changelog
Les changements notables de l'API du parc sont listés dans ce fichier.
Format : Keep a Changelog 2.0.0. Numérotation : versionnage sémantique 2.0.0.
## [Non publié]
### Ajouté
- Filtre par marque sur la liste des postes.
## [1.2.0] - 2026-11-03
### Ajouté
- Ouverture d'un ticket depuis l'intranet (`POST /tickets`).
### Obsolète
- Le paramètre `stock` de `GET /postes` est remplacé par `enStock` ;
il sera supprimé dans la version 2.0.0.
## [1.1.1] - 2026-10-14
### Corrigé
- Les postes en stock n'apparaissaient pas quand on filtrait par type.
### Sécurité
- Mise à jour de la bibliothèque de vérification des jetons JWT, qui
acceptait des jetons expirés dans certains cas.
## [1.1.0] - 2026-09-30
### Ajouté
- Lecture d'un poste par son numéro d'inventaire (`GET /postes/{numInventaire}`).
## [1.0.0] - 2026-09-15
### Ajouté
- Liste des postes de l'inventaire, avec authentification par jeton.
[Non publié]: https://github.com/sorbier-logistique/api-parc/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/sorbier-logistique/api-parc/compare/v1.1.1...v1.2.0
[1.1.1]: https://github.com/sorbier-logistique/api-parc/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/sorbier-logistique/api-parc/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/sorbier-logistique/api-parc/releases/tag/v1.0.0
Les lignes du bas sont des liens de référence Markdown : chaque titre de version devient un lien vers la comparaison avec la version précédente, et la section Non publié vers tout ce qui a changé depuis le dernier tag. Les rubriques vides ne sont pas écrites.
Deux marqueurs complètent le format :
- Les changements incompatibles sont signalés dans leur rubrique (souvent Modifié ou Supprimé) par une étiquette en gras au début de la ligne, que Keep a Changelog écrit
**Breaking:**et qu'une équipe française peut écrire**Rupture :**. L'entrée dit ce qui casse et, en une phrase, comment s'adapter. - Une version retirée pour un bug grave ou une faille reste dans le fichier, avec le marqueur
[YANKED]après sa date (## [1.1.1] - 2026-10-14 [YANKED]) : on ne cache pas une version qui a pu être installée.
Choisir le numéro de version avec SemVer
Le versionnage sémantique (Semantic Versioning, SemVer 2.0.0) donne un sens à chaque nombre de MAJEUR.MINEUR.CORRECTIF. Pour savoir quel nombre augmenter, lis la section Non publié et prends le changement le plus fort :
| Ce que contient la version | Nombre à augmenter | Depuis 1.2.0 |
|---|---|---|
| Au moins un changement incompatible (une route supprimée, un champ renommé, un comportement modifié dont dépendent les clients) | MAJEUR, et les deux autres reviennent à 0 | 2.0.0 |
| Au moins une fonctionnalité ajoutée sans rien casser, ou une fonctionnalité déclarée obsolète | MINEUR, le correctif revient à 0 | 1.3.0 |
| Seulement des corrections compatibles | CORRECTIF | 1.2.1 |
Tant que la version majeure vaut 0 (0.4.2), tout peut changer : le projet est en développement initial. La version 1.0.0 est la première que tu t'engages à garder compatible. Le cours Git et GitHub montre comment poser le tag de version correspondant, et le cours Maintenance applicative comment SemVer guide la mise à jour des dépendances.
CHANGELOG, historique Git et notes de version
Trois documents parlent des changements ; ils n'ont pas le même lecteur.
| Historique Git | CHANGELOG | Notes de version | |
|---|---|---|---|
| Contenu | Chaque commit, avec son auteur et sa date | Les changements notables, par version | Les nouveautés d'une version, mises en valeur |
| Lecteur | Les développeurs du projet | Ceux qui mettent à jour : support, développeurs, administrateurs | Les utilisateurs |
| Où | Dans le dépôt, automatiquement | Dans le dépôt, CHANGELOG.md | Page de release de GitHub ou GitLab, courriel, page « Nouveautés » de l'application |
| Qui l'écrit | Chaque développeur, à chaque commit | L'équipe, à chaque changement notable | L'équipe, à la publication, à partir du CHANGELOG |
Keep a Changelog 2.0 le dit clairement : le CHANGELOG est la source, les notes de version s'en déduisent. Les notes générées automatiquement par une plateforme sont stockées chez elle, pas dans ton dépôt ; le fichier CHANGELOG.md reste la référence. Des outils peuvent préparer un brouillon à partir de messages de commit normalisés (les Conventional Commits du cours Intégration continue), mais une personne choisit ce qui est notable et le réécrit pour le lecteur.
Pour la version 1.2.0, la note destinée aux salariés tient en deux phrases, dans leur vocabulaire : « Nouveau : vous pouvez ouvrir un ticket d'assistance directement depuis l'intranet, menu Assistance. Indiquez le numéro collé sur votre poste pour que le technicien le retrouve tout de suite. »
Exercices
Exercice 1 sur 4 Ranger et numéroter Réussi À revoir
L'API du parc est en version 1.2.0. La section Non publié doit recevoir ces changements :
a. Le tri de la liste des postes était faux pour les numéros supérieurs à PC-0999.
b. Ajout du filtre marque sur GET /postes.
c. Mise à jour d'Express pour corriger une vulnérabilité.
d. Le champ affecteA des postes est renommé utilisateur.
- Range chaque changement dans sa rubrique.
- Quel est le numéro de la prochaine version ? Et si l'on retirait le changement d ?
Voir la réponseMasquer la réponse de l'exercice 1
- a → Corrigé ; b → Ajouté ; c → Sécurité ; d → Modifié, avec l'étiquette Rupture : et une phrase pour s'adapter (« les clients doivent lire
utilisateurau lieu deaffecteA»). - Le changement d casse les clients qui lisent
affecteA: c'est un changement incompatible, la version suivante est 2.0.0. Sans d, le changement le plus fort est l'ajout d'un filtre, compatible : 1.3.0.
Pour éviter une version majeure, une équipe peut ajouter utilisateur tout en gardant affecteA pendant un temps, déclaré dans la rubrique Obsolète : c'est alors une version mineure, et la suppression de affecteA viendra plus tard, en 2.0.0.
Tu avais trouvé ?
Exercice 2 sur 4 Un CHANGELOG à refaire Réussi À revoir
Réécris ce CHANGELOG selon Keep a Changelog. La version a été livrée le 20 novembre 2026.
# Changelog
v1.3
- merge branch 'feature/export'
- fix bug date
- wip export csv
- export csv ok
- update deps (sécurité)
Voir la réponseMasquer la réponse de l'exercice 2
# Changelog
Les changements notables sont listés dans ce fichier.
Format : Keep a Changelog 2.0.0. Numérotation : versionnage sémantique 2.0.0.
## [1.3.0] - 2026-11-20
### Ajouté
- Export CSV de la liste des postes.
### Corrigé
- (préciser le bug de date : ce qui était faux, du point de vue du lecteur)
### Sécurité
- Mise à jour des dépendances (préciser lesquelles et la vulnérabilité corrigée).
Les messages « merge » et « wip » disparaissent : ce sont des étapes de travail, pas des changements. « fix bug date » ne peut pas être réécrit sans savoir ce qui était faux : c'est exactement le défaut d'un CHANGELOG copié du git log. La version s'écrit en entier (1.3.0) et porte sa date.
Tu avais trouvé ?
Exercice 3 sur 4 Ce qui manque au README Réussi À revoir
Le README d'un projet d'étudiant contient seulement : le titre « Gestion des salles », la phrase « Projet réalisé en BTS SIO », la commande npm start. Liste les rubriques qui manquent, par ordre d'importance pour un développeur qui découvre le projet.
Voir la réponseMasquer la réponse de l'exercice 3
- Une description : à quoi sert l'application, pour qui (« Réservation des salles de réunion de Sorbier par les salariés »). « Projet réalisé en BTS SIO » ne dit rien du projet.
- Les prérequis avec leurs versions (Node.js, la base de données).
- L'installation complète : clonage,
npm ci, création de la base, fichier.envà partir de.env.example. Avecnpm startseul, le projet ne démarre pas sur un poste neuf. - La configuration : les variables d'environnement.
- Les tests : la commande qui les lance.
- Des comptes de démonstration par rôle, avec des mots de passe de test.
- Les liens vers la documentation (API, guide utilisateur) et vers le CHANGELOG.
- La licence et le contact.
Tu avais trouvé ?
Exercice 4 sur 4 Des notes de version pour les utilisateurs Réussi À revoir
À partir de l'entrée 1.1.1 du CHANGELOG de l'API du parc, écris une note de version de deux phrases au maximum pour les techniciens du support, qui utilisent l'écran d'inventaire de l'intranet.
Voir la réponseMasquer la réponse de l'exercice 4
« Correction : le filtre par type de l'écran d'inventaire affiche de nouveau les postes en stock. Une mise à jour de sécurité a aussi été installée ; elle ne change rien pour vous. »
La note garde ce qui concerne le lecteur (l'écran qu'il utilise), dans son vocabulaire, et résume la correction de sécurité sans la détailler : le détail technique reste dans le CHANGELOG.
Tu avais trouvé ?