[jira] [Commented] (COUCHDB-1787) Automate release process documentation

["Alexander Shorin (JIRA)" <ji...@apache.org>]

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

Alexander Shorin commented on COUCHDB-1787:
-------------------------------------------

For an ideal spherical project in vacuum, the best CHANGES are `git log tag1..tag2` and the best NEWS are JIRA report for closed issues for release milestone. 

Sphinx version[added,changed] are good markers to highlight what features/statements are changed between versions, but not good one to generate rich and verbose articles. 

Typical versionchanged tag is:

{code}
.. versionchanged:: 1.3 ``eventsource`` feed type added.
{code}

or for CORS that will be just:

{code}
.. versionadded: 1.3
{code}

but these features worths at least several links to RFC specifications and short brief what they are and what they gives for end user.

I believe, that this would be hard to completely automate, but version* tags may simplify process of NEWS/CHANGES generation, helping release manager gather all required information quickly than before: no need to grep git log, just `make changes` and walk through the links.
                
> 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