couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Cottlehuber <...@jsonified.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 Mon, 20 May 2013 13:16:12 GMT
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?


> > I also want to move towards the release notes being thought of as a part
> 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, etc)
> > 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 of
> >> 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. This
> 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 branches
> 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 this
> is
> >> unnecessary now that we're using semver.)
> >>
> >> 2) The documentation should be properly tagged with version information.
> >> 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 produce.
> >>>
> >>> Note that we're NOT trying to satisfy this stories:
> >>>



-- 
Sent from my PDP11

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message