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 13:50:39 GMT
On 21 May 2013 05:13, Alexander Shorin <kxepal@gmail.com> wrote:

>
> Should docs ship NEWS and CHANGES for previous releases or only for
> current one?


I'd suggest we abandon the idea of NEWS and CHANGES all-together. Instead
of using two separate files, let's replace them with one, and call it the
"release notes".

Actually, no one will be happy
> to walk through 1.2.2, 1.2.1 and 1.2.0 notes merging in mind all their
> content to understand what is actually added and fixed. Keeping all
> these stuff within single 1.2.rst might help to figure whole release
> status.
>

Hmm. Not sure.

As you mention, this is how Django does it:

https://docs.djangoproject.com/en/dev/releases/

And looking at this, I think it's fine. I would be quite happy to use this
as a user of Django.

But, I can also see the argument for splitting at the 1.1.x level, or even
the 1.x level.


On 21 May 2013 07:24, Dave Cottlehuber <dch@jsonified.com> wrote:

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


See the work here:

http://wiki.apache.org/couchdb/Merge_Procedure

And the discussion on this thread:

"[DISCUSS] Git workflow"

— http://markmail.org/message/azwohnjdru2aiduv

Specifically, the idea was that when you're merging in features to master,
we have a "merge request" process where you basically have to get explicit
lazy consensus on your merges. And that people are looking to make sure you
have included tests, docs, etc. That is, the addition of the docs becomes a
formalised part of the Git workflow.

> What do you mean "git track changes"?
>
> What I mean is that instead of having in the source tree:
>
> release.1.4.rst
> release.1.3.1.rst
> 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.


Okay, and release.rst has just the release notes for the current release?
(Ant not, as we currently have it in NEWS/CHANGES, that all of the previous
releases are included.)

I don't think this is gonna work. I know it would make it super easy for
devs to contribute to, but I think it would make it super hard for users to
use. Case in point: as a user on 1.0.x, how would I find out what had
changed between my current version and 1.3.x?

Would this involve me going to doc.couchdb.org and flicking between RTD
versions? i.e. Having to select "show me the docs for 1.1.0" then having to
do "okay show me the release notes". And then repeating for each version.
Ugh!


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

Agreed. This seems like a tough problem. And as I'm not the one who's gonna
be solving it, I don't want to prescribe a solution.

One thing that might be good is to do a survey of what other projects are
doing. I mean, we're not the first people in the world to run into this,
right? ;) There's gotta be a few "patterns" that we can borrow from.

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

Sounds good. I think the biggest thing I can do here is step back and let
Alex/you run with it. ;) (Aah, the anxiety of letting go of code you
wrote... Hehe)


-- 
NS

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