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]. Actual changelog entries for a particular release can be determined via git diff and the release tags. Upsides are that it's easy to merge and easy to revert. The downside is that we need to include a timestamp and agree on a timezone that we use for the changelog entries. Vim and Emacs handle this automatically. 2) Just remove the CHANGELOG file all together. We can generate a changelog via `git log` on release of rails. The upside is that we don't need to worry about updating the changelog. The downside is that we put the burden on the release manager to assemble a changelog at release time. Another alternative could be to just not release a changelog at all and ask users to read the git log between tags. Anyway, these are my thoughts. Input is definitely welcome, but I really think this is something we need to change. -- Aaron Patterson http://tenderlovemaking.com/
pgpPfSN7a5Kz1.pgp
Description: PGP signature
