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? > > 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.) > > 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 http://kxepal.iriscouch.com/docs/1.3/changelog.html > > > On 4 May 2013 14:32, Noah Slater <[email protected]> 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. > >> This! > >> 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? > > Let's do it > >> On 4 May 2013 14:26, Noah Slater <[email protected]> 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: > >>> -- Sent from my PDP11
