[
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
