Changelog overhaul

[bitprophet]

Description

Need

We need all of these issues solved in a good changelog setup:

1. Answer "What changes were included in release X?"
2. Answer "What releases included change Y?"
3. Maintain DRY when copying bugfixes from older to newer release lines
4. Minimum dev work for each release

Existing setup

Presently, we maintain one changelog file per release. This handily solves number 1 above. However, it makes number 2 difficult to solve without copying the change entry for a given bug to all applicable changelog files -- which violates number 3 (DRY) and adds a lot of annoying gruntwork (especially as the number of release lines increases) thus violating number 4.

The only other obvious way to honor number 3 in this situation is to have bugfix releases in lockstep, and have higher release lines note that they include the lower release line's bugfixes. (For example, 1.0.2 mentions it includes everything from 0.9.7, and thus 1.0.2 had to be released at the same time as [or later than] 0.9.7.) This is still extra gruntwork for devs and places irritating constraints on when releases can go out, both violations of number 4.

Proposed solution

Have a single changelog file with a continuous timeline of change entries, with releases noted inline. Merge changes from older lines into newer ones, so that each line's changelog is essentially a superset of the older lines' changelog.

This solves problem 1: you can simply look at the items between two releases (from the same release line) and there's your per-release changelog. For example, 1.2.1 back down to 1.2.0. Because the 1.2 line would be getting changelog entries from forward-ported bugfix merges in e.g. 1.1 and 1.0, viewing the 1.2 changelog will be an accurate representation of all changes included.

It solves problem 2 similarly: if the change is listed on the changelog page for a given release, it's in that release.

Problem 3 is solved because there's no more multiple changelog files -- previously version 1.2.1 would contain changelog files for all previous versions and require a copy of the entry in each one (and thus copy/pasting needed at merge time too.) No longer.

Problem 4 is also hopefully solved -- while I need to test it out, the hope is that simply merging into the changelog file will result in the older release line's changes showing up in the correct spot in the timeline (usually "at the top"...). Even if it doesn't, cutting one chunk and pasting it at the top is probably the least amount of work I can expect to do; and we could always flip the order of the changelog around if we really had to.

---

Originally submitted by Jeff Forcier (bitprophet) on 2011-07-08 at 03:53pm EDT

---

Closed as Done on 2011-07-08 at 06:42pm EDT

[bitprophet]

Jeff Forcier (bitprophet) posted:

---

This is all rolled out to 1.0+ (so 1.0, 1.1 and master/1.2).

Seems to work reasonably well; merges will result in conflicts if the recipient has its own additional changelog history, but that's to be expected/is unavoidable, and is pretty easy to manage just like any other such merge conflict. Certainly preferable to copying things around to multiple files.

Also results in a more compact, cleaner representation of the changelog -- I added colorization and line prefixes so bugs/features/support tasks are easily delineated.

Closing this for now, will reopen if complications arise.

---

on 2011-07-08 at 06:42pm EDT