Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: pass (nike.apache.org: domain of kxepal@gmail.com designates
 74.125.82.44 as permitted sender)
MIME-Version: 1.0
In-Reply-To: 
 <CAL+Y1ntPxPGYjM3a0ym9oFSRS9HqU2aD_O9=vFswQwS5eOH8dA@mail.gmail.com>
References: 
 <CAPaJBx4RCSbhPTjADWd85fNhKFB-PYZbwoH+yy12tPqkZDh6Jg@mail.gmail.com>
	<CAPaJBx7qVnvxofYzmBSMVQSWYDhBQT7pGcOVe4OZNA1XfpY1vg@mail.gmail.com>
	<CAPaJBx5T4bfagwK9HU1zQ3vDrb-OpT7UkaLf5KNaOpHS66M7Rw@mail.gmail.com>
	<2CA06D57-686C-4D66-892A-14912D95F3F2@apache.org>
	<CAL+Y1ns=x758JnNnUgWuR2_HdPQE5rhbeBqKrnmiQLbjimpSzQ@mail.gmail.com>
	<CAHdjipKMA_ku+Jb0OKi1DAe8QaYce+FEVLrfBrgv-PvA1uD8bQ@mail.gmail.com>
	<CAPaJBx4i+2aaAJQGws-hByCrdmq75OyLxXvpBibz9mFFha-r1A@mail.gmail.com>
	<CAL+Y1ntPxPGYjM3a0ym9oFSRS9HqU2aD_O9=vFswQwS5eOH8dA@mail.gmail.com>
Date: Tue, 21 May 2013 11:00:41 +0400
Message-ID: 
 <CAHdjipJMGLUkHKK5=MXrksdh63NZDzwA+LTaZkBiMLT7O-ZVEA@mail.gmail.com>
Subject: Re: [DISCUSS] How to generate our release notes (Was: Re: [4/6] git
 commit: updated refs/heads/1.3.x to 5e64395)
From: Alexander Shorin <kxepal@gmail.com>
To: "dev@couchdb.apache.org" <dev@couchdb.apache.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Hi Dave!

> What I mean is that instead of having in the source tree:
>
> release.1.4.rst
> release.1.3.1.rst
> release=E2=80=A6. etc
>
> we just have release.rst, and if you want to see the release notes for
> a specific (historic) version you'll just checkout that branch, or
> link to it directly in the ASF web-browsable repo.

This is bad idea by two reasons:

0. Namespaces are good. Placing all this stuff under release/
directory removes top level pollution.
1. For every new release there is need to copy-paste old release.rst
to release.{version}.rst - that is boring and erroneousness. Naming
them explicitly like 1.3.rst removes this problem from start.
2. Showing version number in url helps to figure to which CouchDB
version this release notes are belongs to. Just release.rst is about
something unspecific.

The use case I'm referencing to is Python docs:
1. http://docs.python.org/dev/whatsnew/
2. http://docs.python.org/3.1/whatsnew/
3. http://docs.python.org/2.7/whatsnew/
etc.

> Alex, I also agree having a single file with the history in it for
> release notes is a Good Thing albeit more work. I can't think of a
> better (less work) way that still makes it easy for users.
>
> Seems we are all in agreement now, how about I summarise this up later
> today (unless somebody beats be to it) and we start working through
> this for 1.3.1 ?

Not agreed by reasons above. Probably I'll make some demo to show.

> Alex/Dirkjan - have you any more outstanding doc bits to merge in? We
> also have Stefan's github PR https://github.com/apache/couchdb/pull/58
> to go in.

I'd take this changes as modified patch into my local repo since I
have a bit different docs structure now. They are not forgotten.

--
,,,^..^,,,