Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Date: Fri, 3 May 2013 12:44:16 +0000 (UTC)
From: "Dave Cottlehuber (JIRA)" <jira@apache.org>
To: dev@couchdb.apache.org
Message-ID: <JIRA.12645823.1367507517674.265015.1367585056871@arcas>
In-Reply-To: <JIRA.12645823.1367507517674@arcas>
References: <JIRA.12645823.1367507517674@arcas>
Subject: [jira] [Commented] (COUCHDB-1787) Automate release process
 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit


    [ https://issues.apache.org/jira/browse/COUCHDB-1787?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13648367#comment-13648367 ] 

Dave Cottlehuber commented on COUCHDB-1787:
-------------------------------------------

Danish, not quite. In the couchdb source https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/doc/src are the .rst format files, and also a conf.py file that uses the sphinx project http://sphinx.pocoo.org/ to build our documentation. You should read up on sphinx to have a better idea of how this works.

Once we enter the release process http://wiki.apache.org/couchdb/Release_Procedure#Preparing_the_Docs , we compile manually lists of changes from git commits, documentation, JIRA tickets, and put them into CHANGES, NEWS, and also into blog posts. This is all manual today.

If we can get this down to a single `make changes` target in our makefile, that calls an extension of python sphinx to extract the information, this whole process becomes much simpler, and more reliable. It also forces us to get better at using docs and commits as a way of tracking these changes.

We'd like to use the .rst tags that Alex mentioned as a way of extracting all significant changes for this current version, and hand that back to the person doing the release to amend as needed. Potentially that amended file can go back into the source tree and then regenerate the 3 output formats - HTML for blog/website update, plain text for CHANGES/NEWS, and wiki content a la http://wiki.apache.org/couchdb/Release_Procedure#Making_the_Release

There's possibly 3 parts here:

- a nice clean python module or script that extends sphinx to extract a list of ..version* tags and builds a suitable list of changes, ordered by version.
- a separate module or script that takes a manually tweaked .rst file and spits out HTML for the blog/website, plain text for CHANGES/NEWS, and if we still do that in future, wiki content
- work on hooking all of this into GNU Makefile which is how we build our releases: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob;f=Makefile.am;hb=HEAD

A reminder for your submission that it's due Friday 5th May, and that you need to follow the guidelines for GSoC. A simple "I want to do this" will be unlikely to get in ;-)

                
> Automate release process documentation
> --------------------------------------
>
>                 Key: COUCHDB-1787
>                 URL: https://issues.apache.org/jira/browse/COUCHDB-1787
>             Project: CouchDB
>          Issue Type: Improvement
>          Components: Build System, Documentation
>            Reporter: Dave Cottlehuber
>              Labels: gsoc2013, sphinx
>
> The release process today contains a large number of manual transformation steps.
> Fixing this will make the release process significantly easier for release managers, as well as less error-prone.
> Ideally the output formats (NEWS, CHANGES in source tree, and HTML snippets for http://couchdb.org/ website and http://blogs.apache.org/couchdb ) can be auto-generated from either the .rst files in share/doc/src using sphinx's .versionaddded/changed tags, or potentially from commit messages if this is appropriate.
> CouchDB documentation is generated today from restructured text using python code, and rolled into the release documentation during `make distcheck`.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira