incubator-couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@apache.org>
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 01:54:03 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message