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
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.
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.