Releasing update to an old version

[aryelgois]

Lets say a project maintains versions 3.x and 2.x.

If a 2.4.1 version needs to be released to fix an issue that does not exist in 3.x branch, the changelog should be added in chronological order of release or in version order?

i.e.

+## [2.4.1] - 2018-02-04
+...
 ## [3.1.1] - 2018-01-13
 ...
 ## [3.1.0] - 2018-01-12
 ...
 ## [3.0.0] - 2018-01-01
 ...
 ## [2.4.0] - 2017-11-06
 ...

or

 ## [3.1.1] - 2018-01-13
 ...
 ## [3.1.0] - 2018-01-12
 ...
 ## [3.0.0] - 2018-01-01
 ...
+## [2.4.1] - 2018-02-04
+...
 ## [2.4.0] - 2017-11-06
 ...

GitHub releases appear like in the first case.
I would prefer the second case.

[reedstrm]

Oh, tough one - each format is useful for a different audience using the changelog - if, sometime in the future, I inherit a system running v 2.4.1 of this software, I'll go looking for that version, in order to scan the fixes available after it. Given correct semantic versioning, I'd like to see the future hypothetical list of 2.4.X and 2.X.Y changes, in a continuous block, so I can see what "safe" upgrades I can make. This also keeps the 3.X.Y changelog nicely grouped, for planning the larger upgrade. However, If I'm more actively involved in coding a project that uses this software, I'd want to be able to just 'check the top' of the changelog, to see what's happened recently.

I think I come down on the 'keep in sematic order' side of this discussion - unless someone can come up with a better strawman for the 'chronological order'. I think that the type of user who would find that most comfortable is likely to have other means of getting in-time-order info, like the commit logs.

[aryelgois]

I just thought of something. Considering the following commit history, where each letter is a release:

          .-----D---E (v2.x)
         /
    A---B---C-----------F (master, v3.x)

Each branch would have its own changelog, without mixing changes from C (v3.0.0) or F with D and E. Unless a merge of both branches were made, the problem in OP would never happen.

If a change must be done on both branches, I think the best is to rebase the commits and duplicate the changelog on each branch, but into different releases:

On master:

# Changelog

## [3.2.5] - 2018-02-25

### Fixed
- Meltdown and Spectre issue

...

## [2.6.0] - 2016-10-09

On v2.x:

# Changelog

## [2.9.2] - 2018-02-25

### Fixed
- Meltdown and Spectre issue

...

## [2.6.0] - 2016-10-09

v2.6.0 would be B in that neat ASCII history ;)

Now the releases are still nicely grouped, and there is no irrelevant release that is not in the actual history for that version.

And for who'd want to be able to just 'check the top' of the changelog, there is the GitHub releases (chronological order), and as always, the git log --all --date-order --decorate --graph --oneline spell command.

The order of releasing should be v2.9.2 before v3.2.5, to appear in this order in GitHub releases

Only if someone had to merge a minor (or even a major) release from another branch, those in between releases would be added to the changelog. And that's the moment to decide if the order will be like the first or second case. As you, I choose to keep in sematic order.

It doesn't make sense to merge v3.x into v2.x, but the opposite would be ok

[HolisticDeveloper]

I think the key thing is that each release also shows a date associated with it. The two together should give the reader the ability to figure out what happened, whichever way you go.

Also, we shouldn't presume that everyone that writes a changelog is using GitHub, or even Git.

[aryelgois]

@HolisticDeveloper you are totally right :)

But the thing about each branch having its own changelog would work on most (all ?) VCS with branch feature, right?

I opened this issue before starting to use keep-a-changelog in my projects, and that question appeared to me. But after giving it a try, I've found a good workflow – I even went to some old projects just to add a Changelog :D it was fun

And rethinking on this issue after @reedstrm answered, I realized it wouldn't happen often, so I explained my thinking

feel free to close this issue, unless you want to wait for someone [to] come up with a better strawman for the 'chronological order'

[HolisticDeveloper]

@aryelgois wrote:

But the thing about each branch having its own changelog would work on most (all ?) VCS with branch feature, right?

Yes, absolutely. It seems like a good approach to me.

[jlmuir]

@aryelgois wrote:

But the thing about each branch having its own changelog would work on most (all ?) VCS with branch feature, right?

The problem with this, though, is that when I look at the changelog for the latest release (i.e., 3.x in your example), I want to see an entry for all previous releases, including 2.x releases. I would not expect the 2.x branch's changelog to include information about the 3.x releases since I feel like it shouldn't "know" about future release series, but I would expect the 3.x branch's changelog to include information about the 2.x releases since it feels like a complete history to me. Doesn't it seem strange that you would look at the changelog of the latest 3.x release and not be able to have a complete history of all releases (e.g., not be able to find an entry for the latest 2.x release that was made after the 3.x branch)?

[aryelgois]

It doesn't seem strange since that change made in another branch is not part of the current branch's history. After a merge, the changes would be present and the changelog would be filled, maybe just having a merge conflict..

Now here comes a problem:

If I fork your project and start working on it, then release a version: it was some bug fixes and I wanted to require it in my main project, but it doesn't look nice to have a dev-master dependency. (Also, my pull request was taking too long to be merged)

Two parallel universes:

1. Eventually you fix the same things by yourself. My release doesn't need to be part of your changelog even if the changes are the same, because you will never merge my pull request and my commits won't exist in your repository (it is the same point of duplicating the changes, as I showed before. A cherry-pick is also a valid example)

2. You merge my pull request. Now the changes are in your source code, but you got a merge conflict because you made a release before.. Since my version tag probably doesn't exist in you repository, you can choose to re-release my version in your repo, or to move my changes into your Unreleased section, then making a release that includes my changes

• If you move to Unreleased, it would fallback to something like universe 1: the changes are present in your source code, but are listed in a different release
• If, however, you decide to re-release my release..
  • It was just a little strange but you can live with that: you merge into an old commit, which is before your newer releases, release and then merge this new branch into master (and you have to choose between chronological or sematic order) [1]
  • Or you got another release with the same numbers, but with unrelated changes. Would you keep both conflicting releases? (maybe differing with original repository suffix. but the universe 1 is better [2])

## [2.3.4 aryelgois/example] - 2018-03-02
...
## [2.3.4] - 2018-01-16

Or somehow I managed to tag the release in a branch inside you repository (maybe I am a collaborator). Things are easier, it is just a merge. You just didn't merge into master and kept the main development, but now those changes are required. Again: choose chronological or sematic and be consistent.

in the conflict above I chose chronological to sort duplicated semantic versions

My point is: the changelog only lists changes that actually exist in the commit history.

• If it is in another branch that is never merged (not even the change is duplicated) it will never appear in the changelog. not even on master
• If it is merged or duplicated, it's from that point that the changelog knows about the change. And how it will appear depends on how you add it
• It is just too much work to maintain another branch which just combines all changelogs

---

Notes:

[1] - it is actually reverse chronological order :)

[2] - @HolisticDeveloper said we shouldn't presume that everyone that writes a changelog is using GitHub

[jlmuir]

@aryelgois wrote:

It doesn't seem strange since that change made in another branch is not part of the current branch's history. After a merge, the changes would be present and the changelog would be filled, maybe just having a merge conflict.

OK, that's fine to me. I thought you were not planning to merge the 2.x branch back into the 3.x branch. But as long as you do merge the 2.x branch into the 3.x branch, then yes, you get the new 2.x release entries in the 3.x changelog, and then I'm happy. :-)

[Ferdi265]

Another note:

If you have branches with differing/divergent CHANGELOG.md files like suggested above, and you release a fix in multiple versions, it might make sense to link to the original fix

Something like

## [2.9.2] - 2018-02-25

### Fixed

- Meltdown and Spectre issue (backported from [3.2.5](insert_link_here))

This might help new developers find and fix faulty backports much more easily