couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <>
Subject Re: [DISCUSS] How to generate our release notes (Was: Re: [4/6] git commit: updated refs/heads/1.3.x to 5e64395)
Date Sat, 04 May 2013 13:32:33 GMT
Cool. Gmail sent that before I had finished.

Okay, so here's what we should be aiming for:

Anyway. If we manage to do this, I think it will be fantastic. As a release
manager, cutting the release will be trivial. I will just get the HTML from
the .rst file that has been kept up-to-date as features have been added,
and I will use that for the blog post, announcement email, etc. The whole
thing will be pre-written for me.

Now, I'm not sure if this addresses Jan's concern. Because it is a manual
process. I am expecting people to do a lot more than just mirror Git commit
messages into an .rst file. This document should be written as a set of
actual release notes. Intended to be read by a user. Again, see the Django
release notes. This isn't just a concat of all the recent Git log. This is
actual documentation.

So this means that, yes, there's gonna be a bit of cherry-picking, and what
have you, to get things updated across multiple release branches. But
I actually think this problem will become much less painful as we move to
time-based release, where the only time we're creating release branches is
when we're cherry picking bugfixes. No more 1.1.x, 1.2.x, 1.3.x all running
in parallel. (See the thread with the feedback from Dale about why this is
unnecessary now that we're using semver.)

2) The documentation should be properly tagged with version information.
Added in, deprecated in, removed in, etc.

Thoughts on this?

On 4 May 2013 14:26, Noah Slater <> wrote:

> Devs,
> Just moving this to it's own thread.
> Why do we have NEWS and CHANGES files? Because they are a part of the GNU
> Coding Standards, and that's what I used when I was writing CouchDB's build
> system. Why does the GNU Coding Standards have these files? Well, CHANGES
> was probably standardised before RCS, as a makeshift way of seeing what had
> changed. And NEWS is clearly some form of primate release notes.
> I think it's safe to say we can nix both these files and figure out a
> better way of doing this. But first, we need to ask: what problem are we
> trying to solve here?
> I think we want to satisfy these two stories:
>  * As a user, I want to know what has changed in this new release.
>  * As a user, I want to know if $feature is in the version of CouchDB I am
> using.
>  * As a release manager, I want the release notes to be easy to produce.
> Note that we're NOT trying to satisfy this stories:
>  * As somebody who cannot look up a Git log, I want record of all changes.
> So, I would suggest the following:
> 1) We maintain a set of release notes in the documentation itself. These
> release notes are updated _by hand_ as features are added, bugs are fixed,
> tests refactored, etc.
> I already started to generate release notes as of a few releases ago:
> At the moment, this is a very manual process for me. And I was basically
> just going through CHANGES, etc, and annoying things.
> What I'm suggesting is that we maintain a single .rst file like this for
> each version. And we keep it up-to-date as we are working on stuff. I'd
> also like to see more information going into this. Single line items are
> great, but we should be aiming for more.
> Here's what we should be aiming for:
> On 15 April 2013 22:00, Dave Cottlehuber <> wrote:
>> On 15 April 2013 20:30, Jan Lehnardt <> wrote:
>> >
>> > On Apr 10, 2013, at 02:52 , wrote:
>> >
>> >> Refactor javascript runner script to handle couchdb restarts. Single
>> interpreter per test.
>> >>
>> >>
>> >> Project:
>> >> Commit:
>> >> Tree:
>> >> Diff:
>> >>
>> >> Branch: refs/heads/1.3.x
>> >
>> > Can you update NEWS & CHANGES with the test suite updates in all the
>> relevant branches?
>> >
>> > Thanks! :)
>> > Jan
>> > --
>> > PS: We should really address not having to do this manually anymore.
>> Noah, would now be
>> > a good time rethinking all this?
>> Now is a good time. Alex has some nice refactoring work that *hint*
>> could be pushed to an asf branch Real Soon Now, and we can roll this
>> into it.
>> In principle what we would need are 2 things:
>> - discplined workflow (oh noes) to ensure that all CHANGES-worthy work
>> has a corresponding update in .rst files, with a suitable
>> `version-added` tag.
>> - some nifty python to pull those version-added tags into a section in
>> the generated docs
>> I can write up the first part, but I'm not comfortable with the 2nd
>> bit, assuming its the right approach. Any takers?
>> A+
>> Dave
> --
> NS


  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message