incubator-couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dave Cottlehuber (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (COUCHDB-1787) Automate release process documentation
Date Fri, 03 May 2013 12:44:16 GMT

    [ 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

Mime
View raw message