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
 209.85.212.169 as permitted sender)
MIME-Version: 1.0
In-Reply-To: 
 <CAPaJBx4i+2aaAJQGws-hByCrdmq75OyLxXvpBibz9mFFha-r1A@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>
Date: Tue, 21 May 2013 08:13:47 +0400
Message-ID: 
 <CAHdjipLVQ7gEd_MSjj-8vJiFvuNbKXLhcW9PUGwO8NrLeM5DAw@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

Noah,

Few questions:

> As a release manage, I am looking for a single document for each release
> that I can:
>
>  * Use for the announcement email
>  * Use for the blog post
>
> As a user, I am looking for a single document tells me:
>
>  * What's in _this specific release_ that I care about

Their content looks the same, don't it?

> While I think that we need one set of notes for each actual release, this
> may be overkill.
>
> One of the things Jan has been complaining about for a while is that it's
> already quite onerous to update NEWS and CHANGES.

Should docs ship NEWS and CHANGES for previous releases or only for
current one? E.g. docs for 1.5 includes release notes and changes for
1.4 and 1.3, 1.4 release - for 1.3 one etc. While it looks as
overhead, it provides user-friendly access to project history (and
latest RTD build).

> So what I would say is that we should be trying to consolidate and simpli=
fy
> as much as possible. (i.e. Maybe have a single place to update/edit.)

In proposed case place is still the single per Y-release. Do we merge
Z-release notes into Y-release one or track them within separate
article? I'd looked on Django notes and found that Z-release one
provides few content while it strictly (in most cases) depended from
one that was introduced in Y-release. Actually, no one will be happy
to walk through 1.2.2, 1.2.1 and 1.2.0 notes merging in mind all their
content to understand what is actually added and fixed. Keeping all
these stuff within single 1.2.rst might help to figure whole release
status.


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


On Tue, May 21, 2013 at 5:54 AM, Noah Slater <nslater@apache.org> wrote:
> Dave,
>
>
>
>
> On 20 May 2013 14:16, Dave Cottlehuber <dch@jsonified.com> wrote:
>
>> On Tuesday, May 7, 2013, Jan Lehnardt wrote:
>>
>> > +1-ish.
>> >
>> > We can make =E2=80=9Cmake a release note entry=E2=80=9D part of the pr=
ocedure of merging
>> > a feature/fix branch to a release branch and that=E2=80=99s that. The =
original
>> > committer(s) can ask the docs team to come up with a commit that does
>> > adds change log info, so we can spread the effort across the team.
>> >
>> > I don=E2=80=99t know about tags and whatnot, isn=E2=80=99t the point o=
f having the docs
>> > in the source repo that we always have the docs paired with the code t=
hat
>> > ships (including all releases that time-wise preceded whatever is the
>> > current state of a release branch)?
>> >
>> > Jan
>> > --
>> >
>> >
>> Yup +1 to that.
>>
>> If we are Mehring into Release branches that's the time to get I right. =
and
>> I think with minimal effort we should at least be able to extract the
>> headings even if further tweaking is needed.
>>
>>
>> On May 4, 2013, at 15:39 , Noah Slater <nslater@apache.org> wrote:
>> >
>> > > Sorry, to clarify: I don't think it's going to be good enough to jus=
t
>> tag
>> > > stuff in the docs, and then generate release notes by exporting thos=
e
>> > tags.
>> > > The result would be unreadable, and incomplete. Test refactoring, fo=
r
>> > > instance. Where do you tag that in the docs? You don't. There's no
>> > logical
>> > > place to include that in the CouchDB Manual. But it should be includ=
ed
>> in
>> > > the release notes.
>> > >
>>
>>
>> I don't see why the release notes can't be part of the source too? Noah =
am
>> i missing something?
>>
>
> Yes, I think the release notes should be kept under share/doc.
>
> My point was that I *don't* think we should be:
>
>  * generating release notes from Git commits, or
>  * generating release notes from "tags" in the documentation (e.g. "chang=
ed
> in 1.4")
>
> Release notes are one of the most important things we produce as a projec=
t.
> (Obviously, secondary to the code itself, documentation, etc.)  We should
> take the time to write them by hand, using tools to assist where possible=
.
>
> I like this but we can just have a single release.rst file, and have git
>> track changes. See what Alex already did with changes
>>
>
> What do you mean "git track changes"?
>
> On 21 May 2013 02:33, Alexander Shorin <kxepal@gmail.com> wrote:
>
>>
>> It's already in upstream (;
>> http://docs.couchdb.org/en/latest/changelog.html
>>
>> However, may be better to split it by release e.g
>>
>
> As a release manage, I am looking for a single document for each release
> that I can:
>
>  * Use for the announcement email
>  * Use for the blog post
>
> As a user, I am looking for a single document tells me:
>
>  * What's in _this specific release_ that I care about
>
>
>> share/doc/src/release/index.rst
>> share/doc/src/release/1.4/index.rst =3D=3D Short brief about release:
>> goals, solutions, features etc.
>> share/doc/src/release/1.4/whatsnew.rst =3D=3D NEWS
>> share/doc/src/release/1.4/changes.rst =3D=3D CHANGES
>> share/doc/src/release/1.4/migration.rst =3D=3D What if we break some bac=
k
>> compatibility?
>> share/doc/src/release/1.4/whatevermaybethere.rst =3D=3D Reserved for fut=
ure
>> usage.
>>
>
> While I think that we need one set of notes for each actual release, this
> may be overkill.
>
> One of the things Jan has been complaining about for a while is that it's
> already quite onerous to update NEWS and CHANGES.
>
> So what I would say is that we should be trying to consolidate and simpli=
fy
> as much as possible. (i.e. Maybe have a single place to update/edit.)
>
> I still think the release notes should be detailed, and more "prose-y" li=
ke
> the Django release notes.
>
> --
> NS