incubator-couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alexander Shorin <kxe...@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)
Date Tue, 21 May 2013 04:13:47 GMT
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 simplify
> 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 “make a release note entry” part of the procedure of merging
>> > a feature/fix branch to a release branch and that’s 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’t know about tags and whatnot, isn’t the point of having the docs
>> > in the source repo that we always have the docs paired with the code that
>> > 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 just
>> tag
>> > > stuff in the docs, and then generate release notes by exporting those
>> > tags.
>> > > The result would be unreadable, and incomplete. Test refactoring, for
>> > > 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 included
>> 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. "changed
> in 1.4")
>
> Release notes are one of the most important things we produce as a project.
> (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 == Short brief about release:
>> goals, solutions, features etc.
>> share/doc/src/release/1.4/whatsnew.rst == NEWS
>> share/doc/src/release/1.4/changes.rst == CHANGES
>> share/doc/src/release/1.4/migration.rst == What if we break some back
>> compatibility?
>> share/doc/src/release/1.4/whatevermaybethere.rst == Reserved for future
>> 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 simplify
> 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" like
> the Django release notes.
>
> --
> NS

Mime
View raw message