On 21 May 2013 05:13, Alexander Shorin <[email protected]> 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 <[email protected]> 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
