17

I'm a noob with git and i would like to know the best practice to create tags and generate/mantain a changelog.

Until now, i always created a readme.md and manually indicate (in the section "changelog") the most important feature

For example:

version 1.0.1

  • changed layout in home
  • added slideshow in gallery
  • etc..

How can i create a changelog (maybe in markdown format) with these characteristics?

  • title of changes based on personalized title/tags title/date
  • changes based on tags or commits

I do not have a clear idea yet, so suggestions are aprreciate

Thanks in advance :)

redmile
  • 345
  • 1
  • 4
  • 13
  • 1
    Have you looked [here](http://stackoverflow.com/questions/7387612/git-changelog-how-to-get-all-changes-up-to-a-specific-tag)? – Mali Aug 12 '13 at 08:16

3 Answers3

17

There are no some common guidelines yet. But a lot of good rules are explained on keep a changelog.

And as they mention:

Don’t let your friends dump git logs into changelogs.

And I fully agree with it.

That's why I created GitHub Changelog Generator that generates a changelog according all these guidelines.

Actually it works with GitHub only, but it present a good example of how a changelog should look like.

It automatically generates a changelog from your tags, issues, labels and pull requests.

For example: This changelog was generated by this script: CHANGELOG.md

Changelog

1.2.5 (2015-01-15)

Full Changelog

Implemented enhancements:

  • Use milestone to specify in which version bug was fixed #22

Fixed bugs:

  • Error when trying to generate log for repo without tags #32

Merged pull requests:

  • PrettyPrint class is included using lowercase 'pp' #43 (schwing)

  • support enterprise github via command line options #42 (glenlovett)

friederbluemle
  • 33,549
  • 14
  • 108
  • 109
skywinder
  • 21,291
  • 15
  • 93
  • 123
  • Does that mean every time we do a commit, we'll have to submit another commit to save the CHANGELOG.md in the repo after every commit? – Janshair Khan Nov 22 '21 at 13:39
3

I suggest you still manually describe the changes in the changelog.

Though, you can link to a generated changes via github diff. For example, the changelog: https://github.com/rspec/rspec-core/blob/master/Changelog.md

And the diff: https://github.com/rspec/rspec-core/compare/v2.14.2...master

You may want to look around in the repositories of some other reference opensource projects where a lot of good practices can be found.

UpAndAdam
  • 4,515
  • 3
  • 28
  • 46
jurglic
  • 3,599
  • 1
  • 17
  • 13
3

Probably my Asnwer is too late, but now I'm using a amazing ruby gem, it read your git log and split by tags, and the output is written in markdown, take a look

https://github.com/kebab-project/katip

rderoldan1
  • 3,517
  • 26
  • 33