=================================
Releases, a Sphinx changelog tool
=================================

About
=====

Releases is a `Sphinx <http://sphinx-doc.org>`_ extension designed to help you
keep a source control friendly, merge friendly changelog file & turn it into
useful, human readable HTML output.

Specifically:

* The source format (kept in your Sphinx tree as ``changelog.rst``) is a
  stream-like timeline that plays well with source control & only requires one
  entry per change (even for changes that exist in multiple release lines).
* The output (when you have the extension installed and run your Sphinx build
  command) is a traditional looking changelog page with a section for every
  release; multi-release issues are copied automatically into each release.
* By default, feature and support issues are only displayed under feature
  releases, and bugs are only displayed under bugfix releases. This can be
  overridden on a per-issue basis.

Some background on why this tool was created can be found in `this blog post
<http://bitprophet.org/blog/2013/09/14/a-better-changelog/>`_.

Usage
=====

Mimic the format seen `in Fabric's changelog
<https://raw.github.com/fabric/fabric/master/docs/changelog.rst>`_:

* Install ``releases`` and update your Sphinx ``conf.py`` to include it in the
  ``extensions`` list setting: ``extensions = ['releases']``.

    * Also set the ``releases_release_uri`` and ``releases_issue_uri`` top
      level options - they determine the targets of the issue & release links
      in the HTML output. Both should have an unevaluated ``%s`` where the
      release/issue number would go.
    * See `Fabric's docs/conf.py
      <https://github.com/fabric/fabric/blob/4afd33e971f1c6831cc33fd3228013f7484fbe35/docs/conf.py#L31>`_
      for an example.

* Create a Sphinx document named ``changelog.rst`` with a top-level header
  followed by a bulleted list.
* Bullet list items should use the ``:support:``, ``:feature:`` or ``:bug:``
  roles to mark issues, or ``:release:`` to mark a release. These special roles
  must be the first element in each list item.

    * Line-items that do not start with an issue role will be considered
      bugs (both in terms of inclusion in releases, and formatting) and,
      naturally, will not be given a hyperlink.

* Issue roles are of the form ``:type:`number[ keyword]```. Keywords are
  optional and may be one of:

    * ``backported``: Given on support or feature issues to denote
      backporting to bugfix releases; will show up in both release types.
    * ``major``: Given on bug issues to denote inclusion in feature, instead
      of bugfix, releases.
    * If ``number`` is ``0`` no issue link will be generated. You can use this
      for items without a related issue.

* Regular Sphinx content may be given after issue roles and will be preserved
  as-is when rendering. For example, in ``:bug:`123` Fixed a bug, thanks
  `@somebody`!``, the rendered changelog will preserve/render "Fixed a bug,
  thanks ``@somebody``!" after the issue link.
* Release roles are of the form ``:release:`number <date>```. Do not place any
  additional content after release roles.

Then build your docs; in the rendered output, ``changelog.html`` should show
issues grouped by release, as per the above rules. Example: `Fabric's rendered
changelog <http://docs.fabfile.org/en/latest/changelog.html>`_.

Changes
=======

In a fit of irony, Releases is too simple for a full Sphinx doc treatment (or
for multiple release lines) and thus doesn't use itself. Here's a by-hand
changelog:

* 2013.11.05: **0.3.0**:

    * Issue #1/#10 - allow using '0' as a dummy issue number, which will result
      in no issue number/link being displayed. Thanks to Markus
      Zapke-Gründemann and Hynek Schlawack for patches & discussion.

        * This feature lets you categorize changes that aren't directly related
          to issues in your tracker. It's an improvement over, and replacement
          for, the previous "vanilla bullet list items are treated as bugs"
          behavior.
        * Said behavior (non-role-prefixed bullet list items turning into
          regular bugs) is being retained as there's not a lot to gain from
          deactivating it.

* 2013.10.04: **0.2.4**:

    * Handful of typos, doc tweaks & addition of a .gitignore file. Thanks to
      Markus Zapke-Gründemann.
    * Fix duplicate display of "bare" (not prefixed with an issue role)
      changelog entries. Thanks again to Markus.
    * Edited the README/docs to be clearer about how Releases works/operates.
    * Explicitly documented how non-role-prefixed line items are preserved.
    * Updated non-role-prefixed line items so they get prefixed with a '[Bug]'
      signifier (since they are otherwise treated as bugfix items.)

* 2013.09.16: **0.2.3**:

    * Fix a handful of bugs in release assignment logic.

* 2013.09.15: **0.2.2**:

    * Python 3 compatibility.

* 2013.09.15: **0.2.1**:

    * Fixed a stupid bug causing invalid issue hyperlinks.
    * Added this README.

* 2013.09.15: **0.2.0**:

  * Basic functionality.


TODO
====

* Tests would be nice.
* Migrate to a directive-driven (vs role-driven) format? Existing format
  evolved from a purely role-oriented, prose-embedded setup; roles are no
  longer really the right way to do this.

    * Pro: possibly cleaner code + source formatting
    * Con: possibly more verbose source formatting if I can't compact things
      enough. Going from 1 line minimum to a, say, 3 or 4 line minimum per
      entry is not (IMHO) acceptable.

* Possibly add more keywords to allow control over additional edge cases.
* Add shortcut format option for the release/issue URI settings - GitHub users
  can just give their GitHub acct/repo and we will fill in the rest.
* Maybe say pre-1.0 releases consider all bugs 'major' (so one can e.g. put out
  an 0.4.0 which is all bugfixes). Iffy because what if you *wanted* regular
  feature-vs-bugfix releases pre-1.0? (which is common.)
* Allow skipping the actual issue number link somehow, sometimes you just don't
  have an issue and it's stupid to make one.