Comment 2 for bug 1308774

This is not just an issue for ChangeLog generation, it affects the versions that pbr generates from the git history. Some examples below. Commits are in the order that they were created in:

Here we tag a release 0.1.0, and then start work on a new feature (0.2.0.dev1). Then we find a bug in 0.1.0 that we fix and tag 0.1.1. Then we merge the fix into the master branch, and suddenly we're back to 0.2.0.dev1 again.

* Merge 0.1.1 [version 0.2.0.dev1]
|\
| * Bug fix (tag: 0.1.1) [version 0.1.1]
* | Feature commit [version 0.2.0.dev2]
* | Feature commit [version 0.2.0.dev1]
|/
* Release 0.1.0 (tag: 0.1.0) [version 0.1.0]

Even worse, we can actually roll back feature and api-breaking versions this way:
* Merge tag '3.0.1' [version 3.1.0.dev1]
|\
| * Fix a bug (tag: 3.0.1) [version 3.0.1]
* | Add another feature [version 3.2.0.dev1]
* | Finish a feature (tag: 3.1.0) [version 3.1.0]
* | Add a feature [version 3.1.0.dev1]
|/
* Release 3.0.0 (tag: 3.0.0) [version 3.0.0]

Here we have two feature releases, 3.0.0 and 3.1.0. We then start work on a new feature release, 3.2.0. We fix a bug in 3.0.0 and tag it 3.0.1, then merge it into master and now we're building 3.1.0.dev1 again.

There is a simple solution, which is to call 'git log' with --first-parent, which will sort the log entries in the correct order. The --first-parent option was added in git 1.5.1: https://github.com/git/git/blob/35f6318d44379452d8d33e880d8df0267b4a0cd0/Documentation/RelNotes/1.5.1.txt#L89