Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: pass (athena.apache.org: domain of dch@jsonified.com designates
 209.85.217.181 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <2CA06D57-686C-4D66-892A-14912D95F3F2@apache.org>
References: 
 <CAPaJBx4RCSbhPTjADWd85fNhKFB-PYZbwoH+yy12tPqkZDh6Jg@mail.gmail.com>
	<CAPaJBx7qVnvxofYzmBSMVQSWYDhBQT7pGcOVe4OZNA1XfpY1vg@mail.gmail.com>
	<CAPaJBx5T4bfagwK9HU1zQ3vDrb-OpT7UkaLf5KNaOpHS66M7Rw@mail.gmail.com>
	<2CA06D57-686C-4D66-892A-14912D95F3F2@apache.org>
Date: Mon, 20 May 2013 15:16:12 +0200
Message-ID: 
 <CAL+Y1ns=x758JnNnUgWuR2_HdPQE5rhbeBqKrnmiQLbjimpSzQ@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: Dave Cottlehuber <dch@jsonified.com>
To: "dev@couchdb.apache.org" <dev@couchdb.apache.org>
Content-Type: multipart/alternative; boundary=001a11c378e40417ee04dd2623e2

--001a11c378e40417ee04dd2623e2
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable

On Tuesday, May 7, 2013, Jan Lehnardt wrote:

> +1-ish.
>
> We can make =93make a release note entry=94 part of the procedure of merg=
ing
> a feature/fix branch to a release branch and that=92s 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=92t know about tags and whatnot, isn=92t the point of having the do=
cs
> 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 t=
ag
> > 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?


> > I also want to move towards the release notes being thought of as a par=
t
> of
> > the documentation. i.e. Not something you can run off with a script.
> > Release notes that are just a list of things (Git commits, doc tags, et=
c)
> > is better than nothing, I guess. But we can do so much better.
> >
> > I was thinking something like:
> >
> > share/doc/src/release/1.3.0.rst
> > share/doc/src/release/1.3.1.rst
> > share/doc/src/release/1.4.0.rst
> >
> > (I am happy to create these files for all our previous releases, if it'=
s
> > something we want to go ahead with.)
>
>

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


http://kxepal.iriscouch.com/docs/1.3/changelog.html


>
> > On 4 May 2013 14:32, Noah Slater <nslater@apache.org> wrote:
> >
> >> Cool. Gmail sent that before I had finished.
> >>
> >> Okay, so here's what we should be aiming for:
> >>
> >> https://docs.djangoproject.com/en/dev/releases/1.5/
> >>
> >> Anyway. If we manage to do this, I think it will be fantastic. As a
> >> release manager, cutting the release will be trivial. I will just get
> the
> >> HTML from the .rst file that has been kept up-to-date as features have
> been
> >> added, and I will use that for the blog post, announcement email, etc.
> The
> >> whole thing will be pre-written for me.
> >>


This!

> >> Now, I'm not sure if this addresses Jan's concern. Because it is a
> manual
> >> process. I am expecting people to do a lot more than just mirror Git
> commit
> >> messages into an .rst file. This document should be written as a set o=
f
> >> actual release notes. Intended to be read by a user. Again, see the
> Django
> >> release notes. This isn't just a concat of all the recent Git log. Thi=
s
> is
> >> actual documentation.
> >>
> >> So this means that, yes, there's gonna be a bit of cherry-picking, and
> >> what have you, to get things updated across multiple release branches.
> But
> >> I actually think this problem will become much less painful as we move
> to
> >> time-based release, where the only time we're creating release branche=
s
> is
> >> when we're cherry picking bugfixes. No more 1.1.x, 1.2.x, 1.3.x all
> running
> >> in parallel. (See the thread with the feedback from Dale about why thi=
s
> is
> >> unnecessary now that we're using semver.)
> >>
> >> 2) The documentation should be properly tagged with version informatio=
n.
> >> Added in, deprecated in, removed in, etc.
> >>
> >> Thoughts on this?
>
>

Let's do it


> >> On 4 May 2013 14:26, Noah Slater <nslater@apache.org> wrote:
> >>
> >>> Devs,
> >>>
> >>> Just moving this to it's own thread.
> >>>
> >>> Why do we have NEWS and CHANGES files? Because they are a part of the
> GNU
> >>> Coding Standards, and that's what I used when I was writing CouchDB's
> build
> >>> system. Why does the GNU Coding Standards have these files? Well,
> CHANGES
> >>> was probably standardised before RCS, as a makeshift way of seeing
> what had
> >>> changed. And NEWS is clearly some form of primate release notes.
> >>>
> >>> I think it's safe to say we can nix both these files and figure out a
> >>> better way of doing this. But first, we need to ask: what problem are
> we
> >>> trying to solve here?
> >>>
> >>> I think we want to satisfy these two stories:
> >>>
> >>> * As a user, I want to know what has changed in this new release.
> >>>
> >>> * As a user, I want to know if $feature is in the version of CouchDB =
I
> >>> am using.
> >>>
> >>> * As a release manager, I want the release notes to be easy to produc=
e.
> >>>
> >>> Note that we're NOT trying to satisfy this stories:
> >>>


--=20
Sent from my PDP11

--001a11c378e40417ee04dd2623e2--