couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@apache.org>
Subject [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:26:53 GMT
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:

http://www.apache.org/dist/couchdb/notes/1.3.0/apache-couchdb-1.3.0.html

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 <dch@jsonified.com> wrote:

> On 15 April 2013 20:30, Jan Lehnardt <jan@apache.org> wrote:
> >
> > On Apr 10, 2013, at 02:52 , wendallc@apache.org wrote:
> >
> >> Refactor javascript runner script to handle couchdb restarts. Single
> interpreter per test.
> >>
> >>
> >> Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
> >> Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/9838eef7
> >> Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/9838eef7
> >> Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/9838eef7
> >>
> >> 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

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