On 21 May 2013 03:54, Noah Slater <[email protected]> wrote: > Dave, > > > > > On 20 May 2013 14:16, Dave Cottlehuber <[email protected]> wrote: > >> 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 <[email protected]> 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? >> > > Yes, I think the release notes should be kept under share/doc. > > My point was that I *don't* think we should be: > > * generating release notes from Git commits, or > * generating release notes from "tags" in the documentation (e.g. "changed > in 1.4") > > Release notes are one of the most important things we produce as a project. > (Obviously, secondary to the code itself, documentation, etc.) We should > take the time to write them by hand, using tools to assist where possible.
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. > 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 >> > > 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. > While I think that we need one set of notes for each actual release, this > may be overkill. Yes. > One of the things Jan has been complaining about for a while is that it's > already quite onerous to update NEWS and CHANGES. Yes. > So what I would say is that we should be trying to consolidate and simplify > as much as possible. (i.e. Maybe have a single place to update/edit.) This. > I still think the release notes should be detailed, and more "prose-y" like > the Django release notes. That too. 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. 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 ? Alex/Dirkjan - have you any more outstanding doc bits to merge in? We also have Stefan's github PR https://github.com/apache/couchdb/pull/58 to go in. A+ Dave
