releases 0.2.4

A Sphinx extension for changelog manipulation

About

Releases is a Sphinx 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.

Usage

Mimic the format seen in Fabric’s changelog:

• 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 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.

• 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.

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.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.