bitprophet/releases

A powerful Sphinx changelog-generating extension.

What is Releases?

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. It's compatible with Python 3.6+, and may work on Sphinx versions as far back as 1.8.x, though 4.x and up are recommended and generally all we will support.

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.

For more documentation, please see http://releases.readthedocs.io. For a roadmap, see the maintainer's roadmap page.

Note

You can install the development version via pip install -e git+https://github.com/bitprophet/releases/#egg=releases.

releases's Issues

Non-backported issues + multiple long-running lines = ugh

Scenario

This kind of picks up from / relates to #17: in that scenario, there were some "active" release lines, then some older inactive ones, and a bug was kinda "shoved down" into the older inactive lines as a one-time thing, which meant cutting some new releases for it. #17's solution of explicit releases solves that fine.

What it does NOT solve is the scenario where you have, say, 2-3 active release lines for a longish period of time (like how I currently try to backport stuff to Paramiko 1.10, 1.11, and 1.12) and a non-major, but also non-backportable (because it fixes a newer feature) bug pops up.

E.g. in my specific case, a feature got introduced in 1.11.0, then it got a bugfix in 1.11.2. The 1.10.x line is still active, but this bugfix did not appear in it as it didn't apply. However, the current rules mean that we assume it WAS backported, so it appears in any 1.10.x releases, which is bad.

Even if I stop supporting 1.10 now, that means I have about 3-4 1.10.x releases that have to be converted to explicit releases (annoying) and if I want to keep supporting it, that annoyance will keep scaling.

Solutions/thoughts

• Allow marking bugs as e.g. "1.11+" and do some basic version math to determine which line buckets they should appear in. Think I had this idea during #17 but because #17's use case was kind of the inverse, it didn't pan out. But it might work here.
• Subversion of above, state ALL release lines it should be in, since the number of these is usually small & we're only indicating it on a handful of non-backported bugs ever. E.g. "1.11, 1.12".
  • Counterpoint: then we have to go back and update those anytime we add new release lines. Not really maintainable.
• Suck it up and just leverage explicit release lists. Boooooo.
• ???

Improve logging

Right now logging is scattershot and uses ye olde local sys.stderr.write functionality, with bonus "rebind to a partial within functions due to requirement of access to app.config to tell whether debug mode is enabled" BS. (The latter being partly Sphinx/docutils' fault, but still.)

Would be nice to:

• Figure out a non awful way to access the config value globally
  • Given that this is a documentation building tool (i.e. not expecting long, persistent processes where state might get confused) & there's difficulties in obtaining the data from Sphinx at arbitrary points in time...I might stoop to "set a module level variable at some point".
• Replace hand-rolled log function with actual logging module (stdlib or other)
• Overhaul actual log lines to be clean, useful, thorough etc.
  • Because it's really dumb to add manual log/print statements when debugging new features or bugs. It's 2016.

Order/sort changelog entries within each release bucket

For nontrivial releases w/ lots of line items, it looks pretty messy to have an effectively unordered list with bug/feature/support all mixed up. Not to mention it's harder to read when you know a given fix is in a given release & are trying to scan for it.

Technically they're sorted temporally (IIRC) but that doesn't usually matter to anybody.

Would like to reorder things per-bucket so they're displayed in feature-bug-support order. Ideally configurable but that's probably a phase 2 kind of thing.

Another phase 2 kind of thing would be to flag specific line items as "major" or "emphasis" and visually highlight them...but that probably belongs in another ticket.

Using releases on readthedocs.org ?

Hello,

I like releases and I'm trying to use it on a project. The docs are hosted on readthedocs.org. The build fails because the releases extension is not available.

Since Fabric documentation is also hosted there, I guess I missed something. Did not found anything in RTD docs.

What did I missed ?

Thanks

NotImplementedError: Unknown node: issue

Using releases 0.6.1 and most earlier versions, I get the same exception as in #22 and #24. Here is the Sphinx error log :

# Sphinx version: 1.2.2
# Python version: 2.7.6
# Docutils version: 0.11 release
# Jinja2 version: 2.7.2
# Loaded extensions:
#   sphinx.ext.todo from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/ext/todo.pyc
#   sphinxcontrib.programoutput from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinxcontrib/programoutput.pyc
#   releases from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/releases/__init__.pyc
#   sphinx.ext.intersphinx from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/ext/intersphinx.pyc
#   sphinx.ext.oldcmarkup from /home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/ext/oldcmarkup.pyc
Traceback (most recent call last):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/cmdline.py", line 254, in main
    app.build(force_all, filenames)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/application.py", line 212, in build
    self.builder.build_update()
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 214, in build_update
    'out of date' % len(to_build))
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 276, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 320, in write
    self._write_serial(sorted(docnames), warnings)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 333, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/builders/html.py", line 433, in write_doc
    self.docwriter.write(doctree, destination)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/writers/html.py", line 51, in translate
    self.document.walkabout(visitor)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "/home/pmuller/dev/ipkg/env/lib/python2.7/site-packages/sphinx/writers/html.py", line 588, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: issue

Since this changelog.rst does not belong to an opensource project, I'll send it to you by e-mail.

I tried many versions of release; and the 0.2.4 version builds this changelog.rst file successfully. More recent ones do not.

Thanks for your help !

Consider expanding 'unreleased XXX' display

When poking around exposing a parsed changelog programmatically (so folks could e.g. figure out whether the changelog needs updating with a release entry at release time) I realized there's data left in the line manager which we don't expose in the finally published changelog.

For example, consider a project with multiple active bugfix lines, say a 1.10 and 1.11, and assume most/all bugs are backported to 1.10.

When it comes time to release, one will go back to 1.10, add a release line to the changelog (and tag and publish and etc etc). At that point in time, everything's great - all bugs are in the new 1.10 release (say 1.10.5), no bugs are in 'unreleased 1.x bugfix', etc.

Now switch to the 1.11 branch, and merge in the 1.10 branch. Problem: even though no 1.11 release line is in the changelog, the 'unreleased 1.x bugfix' "release" is still empty/nonexistent when you render/parse the changelog - because those bugs are now in a release (1.10.5). Even though, from the perspective of 1.11, they are still outstanding/pending/etc.

Now, the internal LineManager object knows this - its [1]['1.11'] release-line bucket is non-empty at end of run. And if one adds an eg 1.11.3 release line, it empties that bucket as one would expect. But we're never exposing that bucket to the rendered changelog.

---

What this means:

• "Unreleased" is narrowly/strictly defined right now, it's 100% literal: did an issue appear in any releases at all?
• In some cases, users may expect different behavior: has an issue been "fully" released into all lines for which it is eligible? (Aka: is it out of all pending buckets?)
• This may mean we want to expand the visual display of 'unreleased' issues so they include non-empty per-line buckets, and not just the 'unreleased' buckets. (I'm not positive, though, thus why this is a "Consider" ticket...)
• The programmatic use case noted up top (which didn't get its own ticket, but will be released shortly) does still want access to this info, but it can be served by simply ensuring we publish both the line manager and the artifact/resulting changelog object/dict. Then users can go "hey, I'm on branch 1.11, but the 1.11 bucket is non-empty - I need to cut a release".

generating changelog fails if there are comments at the top of the file

if changelog.rst has anything above the title, generating docs will fail. you should be able to add comments or other non-visible directives to the top of the file.

Backported support items filtered out of 'next feature release'?

Support items occupy a strange spot between feature and bug; when backported, they frequently don't need to appear in 'next feature release' territory (or, indeed, the actual feature release when it appears.) However sometimes they DO only show up in the next major release.

See e.g. http://note.io/1qiFsND wherein the 'next feature release' looks busier than it really is, because the two support items are both backported.

LICENSE is not a part of the upstream tarball.

Hi.

I am the maintainer of the Debian package of 'releases'. I have noticed that your source tarball does not contain the LICENSE file. Could you please add it to MANIFEST.in

Thanks

Repeat issue #s

Sometimes we have multiple items done by the same PR (I know, I know). It'd be nice to be able to list the same issue number multiple times in the changelog.

'Unknown node: issue' on inline issue roles

Sometime recently (probably during the fixes for 0.5.2 and not before), inline/subsequent issue roles - i.e. ones in the description and not at the start of a line - stopped getting translated correctly, leaving them around until render time, which as usual gets mad.

Have a fix already, need to write a regression test since clearly this wasn't getting tested correctly.

Maybe allow a few more obvious shorthands for semver specs

Spinoff of #45.

Noticed that e.g. in a situation where one puts out a minor release and major release at the same time, one doesn't actually want features in the minor to duplicate into the major all the time - it's implied the major will include them.

So, one wants to do e.g. (>=1.17,<2.0), explicitly. However, as it's a feature and thus only subject to landing in the one minor release bucket, one can more succinctly say (==1.17).

Thus this ticket is for making that even easier and perhaps allowing (1.17), i.e. the == is implicit. Not 100% sure, and assuming folks will only really want to use these syntaxes around (rare) major releases, it's not like we really need the savings. But noting just in case.

Multiple Changelog files?

I have enjoyed using releases on several projects and am looking to use it on several more.

I am wondering if it is possible to process multiple "changelog" files?

The particular situation I have is that I have several small projects around a common theme. I would like to maintain a changelog per project, but would like to maintain only one documentation site for the lot of them. Suggestions on how to do this?

Support for crossing major-version boundaries

I.e. right now, in Paramiko, going from 1.x to 2.x results in: surprise! there's no 2.x displayed anywhere!

Clearly the parse and/or organization logic breaks down in some way, which isn't too surprising, I'm sure there's a lot of assumptions baked in aimed squarely at iterating over minor releases only.

Fixing this may end up solving (fully or partly) #19 and #36.

Remaining todo

• Figure out whether we have solved #19 / #36 or not
• Address whether advanced spec format should imply major/backported behavior or not
• Implement config option re: issues 'sticking' to latest major release family by default

Try reinstating per-release permalinks

Looks like I overlooked the handy permalinks you get with title docutils nodes, when trying to restyle the release-header H2's.

They appear on other, regular titles as e.g. <a class="headerlink" href="#changelog" title="Permalink to this headline">¶</a>.

The targets seem to automagically work still - i.e. the div IDs function, so you can go to a new-style Releases changelog and slap #1.2.3 to the URL and it works right.

But that's effectively invisible to users now.

Support for tags

We are using releases for a number of projects (non-libraries) and often want to label which project a specific issues relates to. Currently this is done like so: :bug:DD-200 *(ProjectA)* Just a flesh wound.

Would it be possible to perhaps get native support for tags/labels where it could also add the CSS class tag-<input-tag> for optional styling? This to get one big changelog for all projects instead of having one for each.

Edit: My initial thought was to support :bug:DD-200 major [projectA, projectB]`` to support multiple labels.

additional lists in changelog break Sphinx

Today I discovered that if you have list above your changelog, Sphinx will choke on it. This is also true if the pre-changelog list is in an included file. Example (broken) changelog:

Changes
=======

- list
- items

more text

- :release:`0.1.0 <2017-02-07>`
- :bug:`1` nothing yet

If nothing else, it would be helpful to provide some sort of useful error message, rather than just crashing Sphinx. This is the error currently shown:

Exception occurred:
  File "c:\program files\python36\lib\site-packages\sphinx\writers\html.py", lin
e 722, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: Release

Support for notes to releases

You can currently add multi-line entries/notes beyond the basic description for features and bugs. (see Release changelog, feature #1). Is it possible to add similar notes to the release entry itself (rather than adding them as, say, support items)?

"Features stick to upcoming major release only" toggle

Leftover from #45. There's a skeleton test for this and possibly an artifact in the docs.

Better error detection

Attempt to detect whether a Sphinx build ran 100% without mutating a changelog, and bail out with a useful error. When this is not done, the only telltale sign is Sphinx-core complaining that it doesn't know what issue or release roles are (because they never got mutated into useful nodes.) This is kinda grody.

The only way I can think to do this offhand is to add A) some state keeping and B) a hook into the step after the one we currently hook into. I.e.:

• Initialize some global variable (meh), e.g. did_a_changelog = False
• Hook into the "build each document" step as we do now; set did_a_changelog = True if we do run.
• In some step after that prior step, test did_a_changelog and die usefully if still False.

Unable to build -- Unknown node "issue"

Hi despite having releases in the extensions list of my docs/source.conf.py I get the following error:

pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 31%] changes                                                                                                                                
Exception occurred:
  File "/home/prologic/.virtualenvs/circuits/lib/python2.7/site-packages/sphinx/writers/html.py", line 588, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: issue
The full traceback has been saved in /tmp/sphinx-err-8G5mEk.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [html] Error 1

Fatal error: local() encountered an error (return code 2) while executing 'make html'

Aborting.

Configuration options should be optional

If I only use the "-" or "0" options in my project, and don't configure the releases_issue_uri and releases_release_uri options in my conf.py file, I get the following stack trace:

Exception occurred:
  File "...\.tox\docs\lib\site-packages\releases\__init__.py", line 129, in release_nodes
    link = '<a class="reference external" href="{0}">{1}</a>'.format(uri, text)
UnboundLocalError: local variable 'uri' referenced before assignment

This is not super user friendly. If the options are required (looks like it from the docs), shouldn't we try to enforce the presence?

Also, since it's possible not to use these at all, can we make it optional? I understand that if someone uses the issue numbers but doesn't set the options, then maybe we'd want a warning or something, but crashing like this is probably not what you had in mind.

I'm willing to send in a patch if you're interested. Just let me know what you want as the final behavior.

Python 3 wheels & general setup.py touch-up

• Think our release process is only making py2 wheels...double check this, figure out why, probably need bdist_wheel -> universal:true in setup.cfg or whatnot.
• Consider setting the option for the release task to sign, because why not
• Ensure up to date with python 3.x classifiers, probably lacking 3.4, 3.5
  • Does PyPy have a classifier now?

LaTeX Support

Hello, I was just wondering if there were any plans to support building LaTeX documentation with this extension? I write a lot of docs that are consumed both as HTML and PDF. I'm excited about the possibilities of this extension, but I'm not sure how I can use it if it can't support both output formats.

Support "only backported so far" for bugfix/backported issues

Scenario:

• Fabric has a bunch of semi-open release lines, e.g 1.5 -> 1.8.
• Some bugfixes get backported only as far as is easy/appropriate, e.g. to 1.7, and when releasing just 1.7/1.8 bugfixes, no problem.
• A serious bug is found going back to 1.5; decision is made to put out bugfixes for 1.5 onwards.
• Now the changelog thinks all the 1.7/1.8 bugfixes were backported to 1.5/1.6, when they were not.

Solutions:

• Never release old stuff. Ehhhh. Not possible, esp given some things are bugfixes to recent new features. I might want to support 1.7/1.8/1.9, issue bugfix to a 1.8 feature, and that should never show up in 1.7.
• Add more annotations (as per TODO item) so I can say "this went back to X".
  • Problem with this is it approaches the "manually note down version control branch info" scenario I was hoping to avoid with all this fancy automagic bullshit.
  • I.e. now every single bugfix or backported feature/support has to note down, at minimum, the oldest branch/line it was backported to.
  • And it's error-prone, anytime you forget this notation and then release an older-than-average bugfix release, poof, extra stuff.
  • Counterarguments: it's not like a single line number is a lot of extra data; and it's not like the existing annotations (major/backported) aren't also error prone. Also...there's really no other option here that I can think of.

Implicit bug line items get incorrectly truncated after backticks

E.g. this changelog:

* Meh. I'm some implicit bugfix. It affects ``some monospaced thing or other`` I guess?

Will render as just:

Meh. I'm some implicit bugfix. It affects 

That's it. Everything after affects is just straight up not in the rendered HTML.

Doesn't impact "real" issues - as soon as you slap :bug: in front, this tendency vanishes.

Suspect it has to do with the way we create the implicit object's docutils nodelist...

Installation failure due to bad signature under Python 2.6

See https://travis-ci.org/vmalloc/slash/jobs/24110248#L384

Patch releases ignored ?

Till now, I only python-releases to manage the Changelog of a library where I incremented the "minor" number between 2 library releases. That worked fine. (eg. "0.1.0", then "0.2.0", etc.)

Now I'm trying to generate a changelog for a patch release (eg. "0.1.0" -> "0.1.1").

But in my tests, patch releases seem to be ignored.
For example:

=========
Changelog
=========

* :release:`0.5.0 <2013-12-16>`
* :feature:`0` Added baz

* :release:`0.4.1 <2013-12-16>`
* :feature:`0` Added bar

* :release:`0.4.0 <2013-12-13>`
* :feature:`0` Added foo

When generating a changelog from this example, The "Added bar" feature shows up in the "0.5.0" release.

If I remove the "0.5.0" release from this example, the "Added bar" feature shows up in the "Unreleased" section (like there was no release tag for "0.4.1").

Is this the expected behavior ?

Thanks !

Porting projects with non-semver history

Hi there!

I've just ported the documentation for on of my older projects to Sphinx and, since I really, really like releases, I was hoping to port that project's change log to releases too.

This project didn't follow semantic versioning until very recently, so a lot of features went in to 1.2.x releases.

I see there's a releases_unstable_prehistory option which seems almost designed for this use case, but (as documented) this doesn't affect 1.0+ releases.

What are your thoughts on this?

Thanks!

Better plan/docs for master-only, young projects

Problem

• Young projects with just a master branch & rapid iteration (like...this project) are often tempted to slam out arbitrary feature releases ("ehhh let's call this 0.3.0"), sometimes with bugfix releases in between, sometimes not - but almost always w/o really keeping release lines, numbers just go up.
• In this setup, the distinction between feature and bugfix releases can be blurred or nonexistent.
• That clashes with how Releases thinks about the world (namely, from a mature-project, multiple-release-line perspective.) Young projects must constantly remember to mark bugs as 'major', at the very least.

Solutions

1. Education only: document the phenomenon of pre-1.0 single-line release setups, remind that "mixed" releases will need to mark up the bugs and/or features as appropriate so they show up right.
2. Logic update: pre-1.0 releases are considered to consume all issues listed since previous release. Maybe make this configurable for users who don't want it.
   • Counterpoint: this could confuse users since the behavior changes post 1.0, possibly "without warning."
3. Do both: document it, make an opt-in (not opt-out) option saying "yes I want lazy pre-1.0 releases that suck up all issues".

Last feels best.

:bug: role requires keyword major?

Maybe I'm just attempting to use this differently then it's designed for, but I have a project which doesn't doesnt a semantic versioning and the version numbers are just YY.MM.NN where NN is just an incrementing version number that gets reset each month.

I noticed if I have this:

* :bug:`56` Add the ``Content-Length`` header to package responses,
  allowing pip to determine the size of the download.
* :release:`13.10.2 <2013-10-02>`
* :release:`13.10.1 <2013-10-02>`
* :release:`13.10.0 <2013-10-02>`

Then nothing gets output, but if I have this:

* :bug:`56 major` Add the ``Content-Length`` header to package responses,
  allowing pip to determine the size of the download.
* :release:`13.10.2 <2013-10-02>`
* :release:`13.10.1 <2013-10-02>`
* :release:`13.10.0 <2013-10-02>`

Then for the "Unreleased" view I can see the bug that was fixed. However if I then release this as 13.10.3 with the major keyword in place the bug is still shown as unreleased. There doesn't seem to be a configuration type that allows me to just build up a "next" release with features and bug fixes and just release it all together whatever the version number is.

'Initial' bugs (vs features) break newer release-line-oriented achitecture

Description

Bugs (explicit or implicit-because-no-issue-role, doesn't matter) listed at the beginning of time before any release entries, break after Releases 1.1.x because the new "derive default version spec for issues" functionality assumes there will always be more than zero line buckets.

This doesn't break for features because their branch in default_spec() is more generic, just taking the major number only (which is filled in by the pre-seeking functionality). But the bug branch looks inside the major-version structures and tries to find out what the latest minor release bucket is. When there are none, kaboom:

Exception occurred:
  File "/Users/jforcier/Code/oss/releases/releases/models.py", line 88, in default_spec
    key for key, value in six.iteritems(lines)
ValueError: max() arg is an empty sequence

Solutions

• Main issue is conceptual: unless the first release is marked as a bugfix release, a regular, non-major bug has nowhere to go until the first actual bugfix release.
  • This is arguably a sub-problem of #19, which is also the type of changelog I am encountering this bug within.
  • This could just be considered part and parcel of #19 insofar as "early/pre-1.0 releases should/could consider all issues as feature-like".
• Could implement a similar pre-seek/look-ahead here as we do for features, i.e. prefill the lines struct with not only major version but next minor version.
  • Plus: feels sensible/obvious
  • Minus: more complexity; still doesn't help with the conceptual issue of "hm wait I put this bug in my changelog but it's not appearing in my first 0.1.0 release". I.e. fixes the symptom but not the root problem
• Documentation/education only: inform users that if this is a problem for them, they should always stick some initial release before any bugs, or ensure pre-first-release items are explicitly marked feature-like in some fashion.
  • This is actually tempting since in my case I am translating a pre-Releases changelog where the first "entry" is simply "First public release" or similar. Put another way, this sort of "pre-release item" only really makes any sense if it's this sort of content-less "START OF TIME LOL" marker. Actual, real bugs can't exist before any releases are out.
  • However we should still put a useful error message around the symptomatic lines of code, so at least users know why it's erroring/unhappy.
• Following from thoughts there...perhaps make it so start-of-time situations where the struct looks the way it does here, trigger a "this is an implicit item, make it act feature-like instead of bug-like" behavior.
  • Plus: solves issue neatly, works well with conceptual notes above
  • Minus: means differing behavior at differing parts of the changelog, which isn't amazing.
    • Counterpoint: this is a very special/corner case, and we also already have some differing behavior stuff with the new-in-1.1 pre-major-release stuff, so there is precedent.

Add support for including fixes in round releases

Currently if a bug is included in a changelog, it will always be "floating" waiting for the next bugfix release, even if the meaning is that it is included in the major release...

It would be nice to add a configuration option to force releases to include bugfixes in their intended place...

Add support for implicit .0 in minor/feature releases?

I have the following changelog:

* :release:`1.1 <2016-03-11>`
* :feature:`-` New feature
* :release:`1.0 <2016-03-10>`
* :feature:`-` Initial release

The "New feature" will appear in the category "Next feature release", even though from a version number point of view the "1.1" is a feature release.

If I add the third version number, it works:

* :release:`1.1.0 <2016-03-11>`
* :feature:`-` New feature
* :release:`1.0.0 <2016-03-10>`
* :feature:`-` Initial release

I think it's a valid use case to use only two version numbers. The funny thing is that if we change the "New feature" to be a "bug", it'll be included in the "1.1", etc.

Even though you decide not to fix it, it might deserve a couple of lines in the documentation ;)

Python 2.7.10
releases 1.2.0

Github convenience link setting

AKA just say "my project is on Github at foo/bar" and you don't have to explicitly give the full interpolated URLs.

Support new RTD theme

But don't drop support for the old one. Maybe even make whatever styling we do, configurable?

Example of new theme not playing super nice with our layout: http://www.structlog.org/en/latest/changelog.html - basically it's just the margin/padding for the headers being "reversed" from what it ought to be. Hopefully easy.

Shuffle language a bit

The codebase/tests/docs are annoyingly confusing now:

• "minor" releases used to indicate feature releases
• "major" bugfix metadata/label used to indicate bugfixes put into feature releases

When those two intersect (which is sometimes) it's extra double confusing.

Think best to:

• Rename 'minor releases' in the docs/code to be 'feature releases' (with mention that they are sometimes 'minor releases' in other systems, e.g. the 'minor version number' is what is updated)
• Update tests/code identifiers to match.
• Leave 'major' bugs along, both so we're not changing actual behavior, and because it makes a little more sense now that 'minor' isn't used to describe the releases they appear in.

Fix multi-paragraph issue entries

Example:

* :bug:`122` Yup.
* :bug:`123` Foo the bars and stuff. blah blah.

  Also more stuff related to 123 cuz wow, such bugfix, very commits, so complex.
* :feature:`120` Some other asshole

Current released version actually ignores the 2nd paragraph for bug 123 due to implementation details.

I have a fix already in place (changes implementation to be more flexible, pull issue out while replacing it, then re-insert instead of recreating structure from whole cloth) but remaining:

• Test suite is now too simplistic due to use of simple lists to fake iterable docutils node objects; needs updating.
• Docutils seems to do dumb ass shit with non complex lists, e.g. http://docutils.sourceforge.net/sandbox/html4strict/data/simple-lists.html
  • The end result for us is that any lists containing 'non simple' list items (such as...the multi paragraph ones that this is about) preserve the paragraphs, which then add trailing whitespace and such, and all others lose the paragraphs they originally had.
  • All other lists look "normal" with regular whitespace between the list-items.
  • So now "random" release sublists look funny and have much more internal spacing than all the others. Looks bad.
  • Action items:
    • see if we can fix with styling, though it'd have to be something all users add to their specific stylesheets :( (or we insert inline styling, which is kinda gross and not cascadable.)
    • or figure out how to work around this modification, such that we either undo the paragraph removal (making everything consistent, if whitespace heavy) or replace multiple paragraphs with <br> tags or something. There's an option for this in docutils, but eg the sphinx-build -A option doesn't seem to do the trick.
      • Latter not great because the general point is to allow users to put arbitrary ReST inside these line items and have them preserved.

Multiple versions with the same major/minor numbers erroneously considered same version

For instance, when including :release:0.0.2 and then :release:0.0.1

Broke 'empty' bug lines

The "line items w/ no leading issue role implicitly become bugs" feature broke sometime recently (hopefully also during the dev for 0.5.2 as with #24) such that some AttributeExceptions got thrown because a list was being passed in, where the code now expects real docutils node objects.

This is fixed but like #24 needs regression tests (and I thought I did have a test for this!)

Include license text in the PyPI tarball

It's a mistake not to ship the LICENSE file in the released tarball--that makes it difficult or impossible for anyone to comply with their desired license terms.

I request this to you per Fedora Licensing Guidelines as I want to package this for the distribution.
See: https://fedoraproject.org/wiki/Packaging:LicensingGuidelines?rd=Packaging/LicensingGuidelines#License_Text.

Add support for arbitrary issue types

I use releases for a GUI app. I find myself making improvements to the UI that are not bug fixes but more cosmetic changes that improve readability or something similar. I don't feel right labeling them as features or support issues either.

Do you think the addition of a cosmetic issue type would make sense?

Tighten up conceptual model for (our) 2.0

After #45 it's become more apparent some things are a bit wonky.

The first one that comes to mind is that the major/backported keywords aren't consistent - a 'backported' feature or support item gets put in both bugfix releases and feature releases, but 'major' bugs are only considered "feature-like" and live in feature releases only.

Given the way we treat bugfix/tertiary releases - "feature releases are assumed to include prior bugfixes implicitly" - this seems incorrect. Either that assumption holds or it doesn't. My inclination is that my earlier inclination about 'backported' feature-like issues appearing in both types, is wrong, and all issues should either get displayed "bug-like" or "feature-like" and never both. As-is it makes the changelogs messier and, as noted, is mentally inconsistent.

However changing this would be backwards incompatible (oh the irony) so we'd want there to be a 2.0 release with this sort of change.

Also a good time to more strongly do away with backported/major or e.g. make them distinct issue types of their own like :major-bug: or :minor-feature (though maybe better terms would be nice since that's confusing wrt major/minor release numbering...heh).

And of course, a good excuse to continue the internals cleanup started with #45.

Changelogs with no releases should appear as just 'unreleased'

Friend of the project @sivy tried to use it for a wholly-unreleased changelog (i.e. no :release: directives whatsoever) and ran into what is probably just an assumption-related bug. See https://gist.github.com/sivy/2cf88b595722ffcb7163 for details. Offhand we should be able to cope with this (the parsing step should end with just the 'unreleased' release object holding all issues, and render as such).

"Delayed bugfix" ordering problem

Ran into this error output in Fabric, e.g. this changelog (n.b. probably was an issue before then but that link is at time of debugging).

Seems to be the following:

• Time starts, let's say 1.0.0
• Bugfix committed (this is the problem child) - let's say bug 1
• Feature commited
• Feature release occurs (this flushes/empties the 'unreleased' list), 1.1.0
• More issues are committed (this adds more items to 'unreleased')
• Bugfix release occurs for the previous release line (the one w/ bug 1 in it), aka 1.0.1
• Kaboom: the attempt to say "ok, these guys are releasing, let me remove them from 'unreleased'" dies because 'unreleased' was cleared out before bug 1 was printed out in the changelog.

How to interpret this?

• Our docs (which I just wrote out explicitly recently, see #15) state that feature releases implicitly include prior bugfixes/bugfix release contents. So in this case, release 1.1.0 would be presumed to include bug 1.
• However, the distinction of "bugfix" vs "bugfix release" is important - in this case the maintainer failed to do the normal thing, namely to put out a bugfix along with the feature release. But they probably did do a merge and so bug 1 probably did get released in 1.1.0.
• Because of how 'unreleased' works, somebody reading the changelog after 1.1.0 went out and before 1.0.1 went out would not see bug 1 anywhere in the list (whereas he would show up under 'unreleased' prior to 1.1.0's release.)
• And after 1.0.1 is added, it "looks like" bug 1 was merged after 1.1.0's release (and so one might assume, wrongly, that 1.1.1 includes it when it comes out.)

How to solve it?

• Probably best to tease out 'unreleased' into bug and feature editions, so that in the above scenario, the 1.1.0 feature release would have "flushed" unreleased features but not unreleased bugfixes. Will experiment.

Try harder to implement test fixtures as regular changelog text, or clean them up

Right now the test suite is largely hand-made, semi-internal data structures, plus various wrappers tying them into real-enough structures that the top level API calls can work with. So e.g. one instantiates Issue and Release objects (or shorthand creating them) in some order, it round-trips into a parsed set of changelog nodes, then that result is introspected and asserted about.

It's pretty thorny, involves a large amount of (kinda ugly) extra test code, many layers due to differing abstraction needs for different tests, and most importantly means test fixtures look nothing like real (or doc example) changelogs - and it'd be nice if that were the case.

IIRC this was done in part because actually rendering Sphinx/ReST text without a real set of doc files on the filesystem was impossible or very hard (and of course, truly touching the FS makes tests that much slower, as per the integration suite).

That was 2-3 years ago and I'm wondering if A) my memory is wrong or B) things have improved since then (Sphinx has seen a good speed of dev in the last year+).

---

If it's still not feasible to do so (or if I am misremembering re: how often we generate things programmatically in a way that a text changelog simply can't handle) we should at least examine tightening up all the generation/manipulation code so it's more consistent & easier to reason about.

Tests cannot be run on win32

[GABI-PC] Thu 04/28/2016 11:23:09.08
J:\dev\workspace\pythonxy-xy-27\src\python\fabric\__workspace\releases
>inv test
You indicated pty=True, but your platform doesn't support the 'pty' module!

invocations requires pty.

Adding this to the official sphinx contributions repo

It would be great to add this extension to the official sphinx contributions repository:
https://bitbucket.org/birkenfeld/sphinx-contrib/

Support for tags with prefix

Is it possible you could make have an option to add custom prefixes to the tree such as v?

In https://libtmux.git-pull.com/en/latest/history.html, I want 0.7.0 to point to https://github.com/tony/libtmux/tree/v0.7.0 instead of https://github.com/tony/libtmux/tree/0.7.0

Doctree has no children.

Whenever I try to generate my docs I am getting the following error.

# Sphinx version: 1.2b2
# Python version: 2.7.2
# Docutils version: 0.11 release
# Jinja2 version: 2.7.1
Traceback (most recent call last):
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/sphinx/cmdline.py", line 247, in main
    app.build(force_all, filenames)
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/sphinx/application.py", line 212, in build
    self.builder.build_update()
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 214, in build_update
    'out of date' % len(to_build))
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 234, in build
    purple, length):
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 134, in status_iterator
    for item in iterable:
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/sphinx/environment.py", line 470, in update_generator
    self.read_doc(docname, app=app)
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/sphinx/environment.py", line 639, in read_doc
    app.emit('doctree-read', doctree)
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/sphinx/application.py", line 358, in emit
    results.append(callback(self, *args))
  File "/Users/myusuf3/.virtualenvs/delorean/lib/python2.7/site-packages/releases/__init__.py", line 264, in generate_changelog
    source = doctree.children[0]
IndexError: list index out of range