web-dev-qa-db-fra.com

Bonnes façons de gérer un changelog en utilisant git?

J'utilise Git depuis un moment maintenant, et j'ai récemment commencé à l'utiliser pour baliser mes versions afin de pouvoir plus facilement suivre les modifications et pouvoir voir quelle version est utilisée par chacun de nos clients (malheureusement, le code en vigueur actuellement). que chaque client ait sa propre copie du site PHP; je change cela, mais c'est lent).

Dans tous les cas, nous commençons à créer une dynamique, je pensais que ce serait vraiment bien de pouvoir montrer aux gens ce qui a changé depuis la dernière version. Le problème, c'est que je n'ai pas mis à jour de journal des modifications, car je ne sais pas trop comment procéder. Pour ce moment particulier, je peux parcourir le journal et en créer un manuellement, mais cela me fatiguera très vite.

J'ai essayé de googler "git changelog" et "git manage Changelog" mais je n'ai rien trouvé qui parle vraiment du flux de travail des modifications de code et de la manière dont cela coïncide avec le changelog. Nous suivons actuellement flux de travail de développement de Rein Henrichs et j'aimerais quelque chose qui va avec.

Y at-il une approche standard qui me manque, ou est-ce un domaine dans lequel chacun fait sa propre chose?

Merci beaucoup pour vos commentaires/réponses!

gitgithubchangelog
195
Topher Fangio

C'était il y a environ 3-4 ans, mais pour les futurs chercheurs, il est maintenant possible de générer de superbes journaux avec:

git log --oneline --decorate

Ou, si vous le voulez encore plus joli (avec couleur pour terminal):

git log --oneline --decorate --color

Pipeter cette sortie vers ChangeLog est ce que j'utilise actuellement dans tous mes projets, c'est tout simplement incroyable.

159
user1241335

Vous pouvez utiliser une sorte de journal git pour vous aider:

git log --pretty=%s                 # only print the subject

Si vous nommez joliment vos branches, de sorte qu'une fusion à maîtriser apparaisse comme quelque chose du genre "Merged branch feature-foobar", vous pouvez abréger les choses en affichant ce message uniquement. fonctionnalité:

git log --pretty=%s --first-parent  # only follow first parent of merges

Vous pourrez peut-être ajouter à cela un script de votre choix, qui pourrait supprimer des bits "branche fusionnée", normaliser le formatage, etc. À un moment donné, vous devez l'écrire vous-même, bien sûr.

Ensuite, vous pouvez créer une nouvelle section pour le journal des modifications une fois par version:

git log [opts] vX.X.X..vX.X.Y | helper-script > changelogs/X.X.Y

et engagez-le dans votre version.

Si votre problème est que ces sujets de validation ne ressemblent en rien à ce que vous voudriez mettre dans un journal des modifications, vous avez à peu près deux options: continuer à tout faire manuellement (et essayer de le suivre plus régulièrement au lieu de jouer à la trappe) au moment de la publication), ou corrigez votre style de message de validation. Une option, si les sujets ne le feront pas pour vous, serait de placer des lignes telles que "change: added feature foobar" dans le corps de vos messages de validation, de sorte que vous puissiez ultérieurement faire quelque chose comme git log --pretty=%B | grep ^change: pour ne saisir que les bits super importants des messages.

Je ne suis pas tout à fait sûr que beaucoup plus que ce git pourrait vraiment vous aider à créer vos changelogs. Peut-être que j'ai mal interprété ce que vous entendez par "gérer"?

56
Cascabel

AVERTISSEMENT: Je suis l'auteur de gitchangelog dont je parlerai dans ce qui suit.

TL; DR: Vous voudrez peut-être vérifier le journal des modifications de gitchangelog ou la sortie ascii qui a généré la précédente.

Si vous voulez générer un journal des modifications à partir de votre historique git, vous devrez probablement prendre en compte:

  • le format de sortie . (ASCII personnalisé pur, type de journal de modifications Debian, Markdow, ReST ...)
  • certains filtres commettent (vous ne voulez probablement pas voir toutes les fautes de frappe ou modifications cosmétiques entrer dans votre changelog)
  • certains commettent des conflits de texte avant d’être inclus dans le journal des modifications. (Assurer la normalisation des messages comme ayant une première lettre en majuscule ou un point final, mais cela pourrait aussi supprimer un balisage spécial dans le résumé)
  • votre historique git est-il compatible ?. La fusion, le balisage, n'est pas toujours aussi facilement supporté par la plupart des outils. Cela dépend de la façon dont vous gérez votre histoire.

Facultativement, vous voudrez peut-être une catégorisation (nouveautés, modifications, corrections de bugs) ...

Avec tout cela à l'esprit, j'ai créé et utilisé gitchangelog . Il est censé tirer parti d'une convention de message git commit pour atteindre tous les objectifs précédents.

Avoir une convention de message de validation est obligatoire pour créer un journal des modifications de Nice (avec ou sans l'aide de gitchangelog).

convention de message de validation

Vous trouverez ci-dessous des suggestions sur ce qu'il pourrait être utile de penser à ajouter à vos messages de validation.

Vous voudrez peut-être séparer vos commits en grosses sections:

  • par intention (par exemple: nouveau, correction, modification ...)
  • par objet (par exemple: doc, packaging, code ...)
  • par public (par exemple: dev, testeur, utilisateurs, etc.)

De plus, vous pourriez vouloir baliser certains commits:

  • en tant que "commises mineures" qui ne devraient pas être sorties dans votre journal des modifications (modifications cosmétiques, petites fautes de frappe dans les commentaires ...)
  • comme "refactor" si vous ne modifiez pas vraiment les fonctionnalités. Ainsi, cela ne devrait pas également faire partie du journal des modifications affiché pour l'utilisateur final par exemple, mais pourrait présenter un intérêt si vous avez un journal des modifications pour les développeurs.
  • vous pouvez également baliser "api" pour marquer les modifications de l'API ou les nouveaux éléments de l'API ...
  • ...etc...

Essayez d'écrire votre message de validation en ciblant les utilisateurs (fonctionnalités) aussi souvent que vous le pouvez.

exemple

Ceci est la norme git log --oneline pour montrer comment ces informations pourraient être stockées ::

* 5a39f73 fix: encoding issues with non-ascii chars.
* a60d77a new: pkg: added ``.travis.yml`` for automated tests. 
* 57129ba new: much greater performance on big repository by issuing only one Shell command for all the commits. (fixes #7)
* 6b4b267 chg: dev: refactored out the formatting characters from GIT.
* 197b069 new: dev: reverse ``natural`` order to get reverse chronological order by default. !refactor 
* 6b891bc new: add utf-8 encoding declaration !minor

Donc, si vous avez remarqué, le format que j'ai choisi est:

{new|chg|fix}: [{dev|pkg}:] COMMIT_MESSAGE [!{minor|refactor} ... ]

Pour voir un résultat de sortie réel, vous pouvez regarder à la fin de la page PyPI de gitchangelog

Pour voir une documentation complète de ma convention de message de commit, vous pouvez voir le fichier de référence gitchangelog.rc.reference

Comment générer un changelog exquis à partir de ceci

Ensuite, il est assez facile de créer un changelog complet. Vous pouvez créer votre propre script assez rapidement ou utiliser gitchangelog.

gitchangelog générera un journal des modifications complet (avec le support de la section comme New, Fix...), et est raisonnablement configurable selon vos propres conventions de validation. Il supporte tout type de sortie grâce à la modélisation via Mustache, Mako templating, et a un moteur hérité par défaut écrit en raw python; tous les 3 moteurs actuels ont des exemples d'utilisation et peuvent générer le journal des modifications sous la forme affichée sur la page PyPI de gitchangelog.

Je suis sûr que vous savez qu'il y a beaucoup d'autres git log to changelog outils également là-bas.

52
vaab

Un plus au point CHANGELOG. Dis-moi si les gens aiment ça.

git log --since=1/11/2011 --until=28/11/2011 --no-merges --format=%B
24
Harshniket Seta

Le script gitlog-to-changelog est très utile pour générer un ChangeLog de style GNU.

Comme indiqué par gitlog-to-changelog --help, Vous pouvez sélectionner les validations utilisées pour générer un fichier ChangeLog à l'aide de l'option --since:

gitlog-to-changelog --since=2008-01-01 > ChangeLog

ou en passant des arguments supplémentaires après --, qui seront passés à git-log (appelée en interne par gitlog-to-changelog):

gitlog-to-changelog -- -n 5 foo > last-5-commits-to-branch-foo

Par exemple, j'utilise la règle suivante dans le niveau supérieur Makefile.am De l'un de mes projets:

.PHONY: update-ChangeLog
update-ChangeLog:
    if test -d $(srcdir)/.git; then                         \
       $(srcdir)/build-aux/gitlog-to-changelog              \
          --format='%s%n%n%b%n' --no-cluster                \
          --strip-tab --strip-cherry-pick                   \
          -- $$(cat $(srcdir)/.last-cl-gen)..               \
        >ChangeLog.tmp                                      \
      && git rev-list -n 1 HEAD >.last-cl-gen.tmp           \
      && (echo; cat $(srcdir)/ChangeLog) >>ChangeLog.tmp    \
      && mv -f ChangeLog.tmp $(srcdir)/ChangeLog            \
      && mv -f .last-cl-gen.tmp $(srcdir)/.last-cl-gen      \
      && rm -f ChangeLog.tmp;                               \
    fi

EXTRA_DIST += .last-cl-gen

Cette règle est utilisée au moment de la publication pour mettre à jour ChangeLog avec les derniers messages de validation non encore enregistrés. Le fichier .last-cl-gen Contient l'identifiant SHA1 de la dernière validation enregistrée dans ChangeLog et est stocké dans le référentiel Git. ChangeLog est également enregistré dans le référentiel, de sorte qu'il peut être modifié (par exemple, pour corriger des fautes de frappe) sans modifier les messages de validation.

22
Roland Levillain

La meilleure pratique étant de créer une balise par version, vous pouvez partitionner votre journal des modifications par version. Dans ce cas, cette commande pourrait vous aider:

git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B
18
bithavoc

Pour GitHub projets cela pourrait être utile: github-changelog-generator

Il génère le journal des modifications à partir des balises des problèmes fermés et des demandes d'extraction fusionnées.

This CHANGELOG.md a été généré par ce script.

Exemple:

Changelog

1.2.5 (2015-01-15)

Changelog complet

Améliorations apportées:

  • Utilisez jalon pour spécifier dans quelle version le bogue a été corrigé # 22

Bugs corrigés:

  • Erreur lors de la tentative de génération du journal pour le dépôt sans balises # 32

Demandes d'extraction fusionnées:

  • La classe PrettyPrint est incluse en minuscule 'pp' # 4 ( schwing )

  • soutenir l'entreprise avec les options de la ligne de commande # 42 ( glenlovett )

14
skywinder

J'ai aussi fait une bibliothèque pour cela. Il est entièrement configurable avec un modèle Moustache. Qui peut:

  • Être stocké dans un fichier, comme CHANGELOG.md .
  • Être posté sur MediaWiki
  • Ou simplement être imprimé sur STDOUT

J'ai aussi fait:

Plus de détails sur Github: https://github.com/tomasbjerre/git-changelog-lib

En ligne de commande:

npx git-changelog-command-line -std -tec "
# Changelog

Changelog for {{ownerName}} {{repoName}}.

{{#tags}}
## {{name}}
 {{#issues}}
  {{#hasIssue}}
   {{#hasLink}}
### {{name}} [{{issue}}]({{link}}) {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
   {{/hasLink}}
   {{^hasLink}}
### {{name}} {{issue}} {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
   {{/hasLink}}
  {{/hasIssue}}
  {{^hasIssue}}
### {{name}}
  {{/hasIssue}}

  {{#commits}}
**{{{messageTitle}}}**

{{#messageBodyItems}}
 * {{.}} 
{{/messageBodyItems}}

[{{hash}}](https://github.com/{{ownerName}}/{{repoName}}/commit/{{hash}}) {{authorName}} *{{commitTime}}*

  {{/commits}}

 {{/issues}}
{{/tags}}
"

Ou à Jenkins:

enter image description here

10
Tomas Bjerre
git log --oneline --no-merges `git describe --abbrev=0 --tags`..HEAD | cut -c 9- | sort

Est ce que j'aime utiliser. Il reçoit tous les commits depuis la dernière balise. cut supprime le hash de commit. Si vous utilisez des numéros de ticket au début de vos messages de validation, ils sont regroupés avec sort. Le tri est également utile si vous préfixez certaines commits avec fix, typo, etc.

3
orkoden

Basé sur bithavoc , il répertorie les last tag jusqu'à HEAD. Mais j'espère lister les logs entre 2 tags.

// 2 or 3 dots between `YOUR_LAST_VERSION_TAG` and `HEAD`
git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B

Liste des journaux entre 2 tags.

// 2 or 3 dots between 2 tags
git log FROM_TAG...TO_TAG

Par exemple, il listera les journaux de v1.0.0 à v1.0.1.

git log v1.0.0...v1.0.1 --oneline --decorate
2
AechoLiu

Pour un changelog de style GNU , j'ai cuit la fonction

gnuc() {
  {
    printf "$(date "+%Y-%m-%d")  John Doe  <[email protected]>\n\n"
    git diff-tree --no-commit-id --name-only -r HEAD | sed 's/^/\t* /'
  } | tee /dev/tty | xsel -b
}

Avec ça:

  • Je valide mes modifications périodiquement pour les sauvegarder et les rebaser avant de faire la dernière modification dans le journal des modifications.
  • puis lancez: gnuc

et maintenant mon presse-papiers contient quelque chose comme:

2015-07-24  John Doe  <[email protected]>

        * gdb/python/py-linetable.c (): .
        * gdb/python/py-symtab.c (): .

Ensuite, j'utilise le presse-papiers comme point de départ pour mettre à jour le journal des modifications.

Il n’est pas parfait (par exemple, les fichiers doivent être relatifs à leur chemin ChangeLog, donc python/py-symtab.c sans pour autant gdb/ depuis que je vais éditer le gdb/ChangeLog), mais est un bon point de départ.

Des scripts plus avancés:

Je suis cependant d’accord avec Tromey: dupliquer les données de commit git dans le ChangeLog est inutile.

Si vous voulez créer un journal des modifications, faites-en un bon résumé de ce qui se passe, éventuellement comme spécifié à l'adresse http://keepachangelog.com/

1
Ciro Santilli 新疆改造中心996ICU六四事件

Je laisse le serveur CI transférer les informations suivantes dans un fichier nommé CHANGELOG pour chaque nouvelle version avec la date définie dans le nom de fichier de la version:

>git log --graph --all --date=relative --pretty=format:"%x09 %ad %d %s (%aN)"
1
Lorenz Lo Sauer