couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Cottlehuber <>
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 06:24:28 GMT
On 21 May 2013 03:54, Noah Slater <> wrote:
> Dave,
> On 20 May 2013 14:16, Dave Cottlehuber <> 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 <> 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.

Sure. I am just trying to find an angle that allows us to capture
release note-related information early on, specifically at the time of
merging commits in, rather than ad hoc just prior to the release. And
ideally with as little manual work as 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"?

What I mean is that instead of having in the source tree:

release…. 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.

> 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.

That too.

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 ?

Alex/Dirkjan - have you any more outstanding doc bits to merge in? We
also have Stefan's github PR
to go in.


View raw message