On Thu, Nov 17, 2011 at 10:25:35AM -0800, Aaron Patterson wrote: > We need to do something about our changelogs. First I will explain the > problem, then I will propose a couple solutions. > > When we make a change, that change should be committed to the master > branch. Ideally, that change would also include an entry in the > CHANGELOG file. If it's a bugfix, we'll propagate the change up to each > release branch (3-0-stable, 3-1-stable, etc). > > We have headings in each CHANGELOG. The heading is a version of rails, > and all entries below each heading are supposed to be changes in that > particular version. > > This causes a huge problem when backporting. Let's say we commit > a bugfix to master. At the time of commit, we're not sure if it will be > backported, so we add an entry under the current 3.2 heading. Later we > decide it should be backported. Now we have to merge the commit to the > release branch, then add another commit to master moving the changelog > entry underneath the 3.1.x heading. > > We can also have the problem in the opposite direction. Say we need to > revert a change on the release branch and move the commit back to the > 3.2 release. Now we must make another commit on master to fix the > location of changelog comment. > > I think this way of changelog management is not only very cumbersome, > but also very error prone. There are many ways that we can lose > changelog entries, or simply have them in the wrong place. > > I think there are a couple ways to solve this problem, but we (the core > team) need to agree on it. > > 1) Remove the version headings from the CHANGELOG and simply keep > entries in a reverse chronological order. This is how we keep > changelogs in ruby-core[1].
Forgot to include a link to what the ruby-core changelog looks like: https://github.com/ruby/ruby/blob/trunk/ChangeLog -- Aaron Patterson http://tenderlovemaking.com/
pgp8Y8iZdQPNa.pgp
Description: PGP signature
