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 Sat, 04 May 2013 13:39:02 GMT
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 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.)


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.
>
> 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?
>
>
> 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:
>>
>>  * As somebody who cannot look up a Git log, I want record of all changes.
>>
>> So, I would suggest the following:
>>
>> 1) We maintain a set of release notes in the documentation itself. These
>> release notes are updated _by hand_ as features are added, bugs are fixed,
>> tests refactored, etc.
>>
>> I already started to generate release notes as of a few releases ago:
>>
>> http://www.apache.org/dist/couchdb/notes/1.3.0/apache-couchdb-1.3.0.html
>>
>> At the moment, this is a very manual process for me. And I was basically
>> just going through CHANGES, etc, and annoying things.
>>
>> What I'm suggesting is that we maintain a single .rst file like this for
>> each version. And we keep it up-to-date as we are working on stuff. I'd
>> also like to see more information going into this. Single line items are
>> great, but we should be aiming for more.
>>
>> Here's what we should be aiming for:
>>
>>
>>
>> On 15 April 2013 22:00, Dave Cottlehuber <dch@jsonified.com> wrote:
>>
>>> On 15 April 2013 20:30, Jan Lehnardt <jan@apache.org> wrote:
>>> >
>>> > On Apr 10, 2013, at 02:52 , wendallc@apache.org wrote:
>>> >
>>> >> Refactor javascript runner script to handle couchdb restarts. Single
>>> interpreter per test.
>>> >>
>>> >>
>>> >> Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
>>> >> Commit:
>>> http://git-wip-us.apache.org/repos/asf/couchdb/commit/9838eef7
>>> >> Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/9838eef7
>>> >> Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/9838eef7
>>> >>
>>> >> Branch: refs/heads/1.3.x
>>> >
>>> > Can you update NEWS & CHANGES with the test suite updates in all the
>>> relevant branches?
>>> >
>>> > Thanks! :)
>>> > Jan
>>> > --
>>> > PS: We should really address not having to do this manually anymore.
>>> Noah, would now be
>>> > a good time rethinking all this?
>>>
>>> Now is a good time. Alex has some nice refactoring work that *hint*
>>> could be pushed to an asf branch Real Soon Now, and we can roll this
>>> into it.
>>>
>>> In principle what we would need are 2 things:
>>>
>>> - discplined workflow (oh noes) to ensure that all CHANGES-worthy work
>>> has a corresponding update in .rst files, with a suitable
>>> `version-added` tag.
>>> - some nifty python to pull those version-added tags into a section in
>>> the generated docs
>>>
>>> I can write up the first part, but I'm not comfortable with the 2nd
>>> bit, assuming its the right approach. Any takers?
>>>
>>> A+
>>> Dave
>>>
>>
>>
>>
>> --
>> NS
>>
>
>
>
> --
> NS
>



-- 
NS

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