On Thu, Nov 17, 2011 at 11:25 AM, Aaron Patterson <[email protected]>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]. > > 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. > 2b) Kill the CHANGELOG and use NEWS-style meaningful release notes instead. https://github.com/ruby/ruby/blob/trunk/NEWS https://github.com/ruby/ruby/blob/ruby_1_9_3/NEWS https://github.com/ruby/ruby/blob/ruby_1_8_7/NEWS -- You received this message because you are subscribed to the Google Groups "Ruby on Rails: Core" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/rubyonrails-core?hl=en.
