2

Suppose I am developing an application with the following versions currently available:

  • Latest stable: 1.3.0
  • Latest beta: 1.3.1
  • Latest alpha: 2.0.0

The project has a main branch for 2.x development and v1 for stable 1.x releases. I push a change to main and add it the changelog in main under 2.0.0 accordingly. Let's say I then backport a change from main that becomes part of the 1.3.1 release, and update the changelog in v1 under the new 1.3.1 section. Suppose version 2.0.0 is then released.

How should I update the changelog in main in this case? Do I include the change under both 1.3.1 and 2.0.0 sections? Or do I move the change from 2.0.0 down to 1.3.1 because the latter came out first?

Danny
  • 131
  • 4

2 Answers2

3

It depends on how much of the order of development you want to make public to the users of your app, and how much you want to give users the illusion of a sequentially ordered release sequence.

If "2.0.0" is released after 1.3.1, you can write the changelog for 2.0.0 as if 2.0.0 followed 1.3.1 which followed 1.3.0 (even if your internal development order was different). In this case, you can describe the backported change in the 1.3.1 section. This makes it a little bit easier for the readers of the changelog to understand that all changes from 1.3.1 are also included in 2.0.0. It may also give readers of the 2.0.0 changelog a hint that installing 1.3.1 may be useful or sufficient for them, without having to read the 1.3.1 changelog, too.

However, imagine you released 2.0.0 before 1.3.1 (with a change documented under the 2.0.0 section of the changelog), and then start to backport a new change from the 2.1.x line to 2.0.1 and 1.3.1 in parallel, then the changelog of the release 2.0.1 will contain no 1.3.1 section. In this case, both changelogs (of 2.0.1 as well as of 1.3.1) should contain a description bug XYZ fixed within different sections. If you like, you could add also mention in the 2.0.1 section that the same change was backported to 1.3.1, or vice versa.

At the end of the day, the important part is that each release's changelog tells the users correctly what they get with the release - whether a change was introduced during development of 2.0.0, 1.3.1 or 1.3.0 is often less important in retrospective. Still, it will be definitely more convenient when users don't find conflicting information in two different changelogs.

Doc Brown
  • 218,378
2

Every branch should stand on its own. Your 1.3.1 was probably branched from 1.3 and that’s where its history starts. And every change to the 1.3.1 branch gets an entry in the 1.3.1 changelog.

It doesn’t matter where the change comes from. Even if copied from 2.0.0 it’s a change in 1.3.1 and is entered into your 1.3.1 changelog. You can mention that it is derived from a 2.0.0 change, but it’s in the 1.3.1 changelog. Obviously in the 2,0.0 changelog as well.

gnasher729
  • 49,096