J'utilise Git depuis un certain temps maintenant, et j'ai récemment commencé à l'utiliser pour baliser mes versions afin que je puisse plus facilement suivre les changements et être en mesure de voir quelle version chacun de nos clients exécute (malheureusement, le code exige actuellement que chaque client ait sa propre copie du site PHP; je change cela, mais c'est lent).

En tout cas, nous commençons à créer une certaine 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 est que je n'ai pas tenu de journal des modifications parce que je n'ai pas une bonne idée de la façon de procéder. Pour ce moment particulier, je peux parcourir le journal et en créer un manuellement, mais cela se fatiguera très rapidement.

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

Existe-t-il une approche standard qui me manque, ou s'agit-il d'un domaine où chacun fait son propre travail?

Merci beaucoup pour vos commentaires / réponses!

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

git log --oneline --decorate

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

git log --oneline --decorate --color

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

Vous pouvez utiliser une saveur de git log pour vous aider:

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

Si vous nommez bien vos branches, de sorte qu'une fusion vers master apparaisse comme quelque chose comme "Fobar de fonctionnalité de branche fusionnée", vous pouvez raccourcir les choses en affichant uniquement ce message, et pas tous les petits commits que vous avez fusionnés, qui forment ensemble le fonctionnalité:

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

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

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 validez-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: continuez à tout faire manuellement (et essayez de le suivre plus régulièrement au lieu de jouer à catch- au moment de la sortie), ou corrigez votre style de message de validation. Une option, si les sujets ne vont pas le faire pour vous, serait de placer des lignes comme "change: foobar de fonctionnalité ajoutée" dans le corps de vos messages de commit, afin que plus tard vous puissiez faire quelque chose comme git log --pretty=%B | grep ^change:pour ne saisir que ces super -bits importants des messages.

Je ne sais pas vraiment combien plus que ce git pourrait vraiment vous aider à créer vos changelogs. J'ai peut-être mal interprété ce que vous entendez par «gérer»?

AVERTISSEMENT: je suis l'auteur de gitchangelog dont je parlerai dans la suite.

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

Si vous souhaitez générer un journal des modifications à partir de votre historique git, vous devrez probablement considérer:

• le format de sortie . (ASCII personnalisé pur, type de changelog Debian, Markdow, ReST ...)
• certains filtrage de validation (vous ne voulez probablement pas voir toutes les modifications de typo ou cosmétiques dans votre journal des modifications)
• certains commettent des disputes de texte avant d'être inclus dans le changelog. (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 pris en charge par la plupart des outils. Cela dépend de la façon dont vous gérez votre historique.

En option, vous voudrez peut-être une catégorisation (nouvelles choses, modifications, corrections de bugs) ...

Avec tout cela à l'esprit, j'ai créé et utilisé gitchangelog . Il est destiné à 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 joli journal des modifications (avec ou sans utilisation gitchangelog).

validation de la convention de message

Voici des suggestions sur ce qui pourrait être utile de penser à ajouter dans vos messages de validation.

Vous voudrez peut-être séparer grossièrement vos commits en grandes sections:

• par intention (par exemple: nouveau, corriger, changer ...)
• par objet (par exemple: doc, packaging, code ...)
• par public (par exemple: dev, testeur, utilisateurs ...)

De plus, vous pouvez vouloir marquer certains commits:

• comme des commits "mineurs" qui ne devraient pas être affichés dans votre journal des modifications (modifications cosmétiques, petite faute de frappe dans les commentaires ...)
• comme "refactor" si vous n'avez pas vraiment de changements de fonctionnalités significatifs. Ainsi, cela ne devrait pas également faire partie du journal des modifications affiché pour l'utilisateur final, par exemple, mais pourrait être intéressant si vous avez un journal des modifications pour les développeurs.
• vous pouvez également marquer avec "api" pour marquer les changements d'API ou de nouveaux trucs d'API ...
• ...etc...

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

exemple

C'est standard git log --onelinepour 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 l'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 validation, vous pouvez voir le fichier de référence gitchangelog.rc.reference

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

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

gitchangeloggénérera un journal des modifications complet (avec un support de sectionnement comme New, Fix...), et est raisonnablement configurable selon vos propres conventions de validation. Il prend en charge tout type de sortie grâce à Templating à travers Mustache, Mako templatinget dispose d' un moteur hérité par défaut écrit en python brut; tous les 3 moteurs actuels ont des exemples de la façon de les utiliser et peuvent générer des journaux de modifications comme celui affiché sur la page PyPI de gitchangelog.

Je suis sûr que vous savez qu'il ya beaucoup d'autres git logà changelogoutils là - bas aussi.

Un plus au point CHANGELOG. Dites-moi si vous aimez ça.

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

Le gitlog-to-changelogscript est pratique pour générer un style GNU ChangeLog.

Comme indiqué par gitlog-to-changelog --help, vous pouvez sélectionner les validations utilisées pour générer un ChangeLogfichier en utilisant soit 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és 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 au niveau supérieur Makefile.amde 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 ChangeLogavec les derniers messages de validation non encore enregistrés. Le fichier .last-cl-gencontient l'identifiant SHA1 du dernier commit enregistré ChangeLoget est stocké dans le référentiel Git. ChangeLogest également enregistré dans le référentiel, de sorte qu'il peut être édité (par exemple pour corriger les fautes de frappe) sans altérer les messages de validation.

Étant donné que la création d'une balise par version est la meilleure pratique, vous souhaiterez peut-être 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

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

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

Ce CHANGELOG.md été généré par ce script.

Exemple:

Changelog

1.2.5 (2015-01-15)

Journal des modifications complet

Améliorations mises en œuvre:

• Utilisez un 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 d'un journal pour le dépôt sans balises # 32

Demandes de tirage fusionnées:

• La classe PrettyPrint est incluse à l'aide de «pp» minuscule # 43 ( schwing )

• prise en charge de github d'entreprise via les options de ligne de commande # 42 ( glenlovett )

J'ai aussi fait une bibliothèque pour ça. 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 tout simplement être imprimé sur STDOUT

J'ai aussi fait:

• Un plugin Gradle
• Un plugin Maven
• Un plugin Jenkins
• Un plugin Bitbucket Server
• Un outil en ligne de commande

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

Depuis la 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:

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

C'est ce que j'aime utiliser. Il obtient tous les commits depuis la dernière balise. cutse débarrasse du hachage de validation. Si vous utilisez des numéros de ticket au début de vos messages de validation, ils sont regroupés avec sort. Tri aide également si vous préfixer certains commits avec fix, typoetc.

Je laisse le serveur CI diriger les éléments suivants dans un fichier nommé CHANGELOGpour chaque nouvelle version avec la date définie dans le nom du fichier de version:

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

Pour un journal des modifications de style GNU , j'ai préparé 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 périodiquement mes modifications pour les sauvegarder et les rebaser avant de faire la modification finale du ChangeLog
• 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 ChangeLog.

Ce n'est pas parfait (par exemple, les fichiers doivent être relatifs à leur chemin ChangeLog, donc python/py-symtab.csans gdb/puisque je vais éditer le gdb/ChangeLog), mais c'est un bon point de départ.

Scripts plus avancés:

• https://github.com/tromey/git-gnu-changelog par Tromey, un mainteneur GDB
• GCC de la contrib / mklog
• https://github.com/davidmalcolm/gcc-refactoring-scripts/blob/1fc7fe038bffbb2b48d0a7a300625639f01aefa1/generate-changelog.py

Je dois cependant être d'accord avec Tromey: la duplication des données de git commit dans le ChangeLog est inutile.

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

Basé sur bithavoc , il répertorie le last tagjusqu'à HEAD. Mais j'espère lister les logs entre 2 balises.

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

Liste les journaux entre 2 balises.

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

Par exemple, il répertorie les journaux de v1.0.0à v1.0.1.

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