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. 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"? On 21 May 2013 02:33, Alexander Shorin <[email protected]> wrote: > > It's already in upstream (; > http://docs.couchdb.org/en/latest/changelog.html > > However, may be better to split it by release e.g > As a release manage, I am looking for a single document for each release that I can: * Use for the announcement email * Use for the blog post As a user, I am looking for a single document tells me: * What's in _this specific release_ that I care about > share/doc/src/release/index.rst > share/doc/src/release/1.4/index.rst == Short brief about release: > goals, solutions, features etc. > share/doc/src/release/1.4/whatsnew.rst == NEWS > share/doc/src/release/1.4/changes.rst == CHANGES > share/doc/src/release/1.4/migration.rst == What if we break some back > compatibility? > share/doc/src/release/1.4/whatevermaybethere.rst == Reserved for future > usage. > While I think that we need one set of notes for each actual release, this may be overkill. One of the things Jan has been complaining about for a while is that it's already quite onerous to update NEWS and CHANGES. 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.) I still think the release notes should be detailed, and more "prose-y" like the Django release notes. -- NS
