search

bitprophet / releases

A powerful Sphinx changelog-generating extension.
http://releases.readthedocs.io/
BSD 2-Clause "Simplified" License
176 stars 41 forks source link

Tighten up conceptual model for (our) 2.0 #50

Open bitprophet opened 8 years ago

bitprophet commented 8 years ago

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.

MinchinWeb commented 8 years ago

Rather than hard defining :major-bug: and :minor-feature:, would it make sense (or is it even possible) to arbitrary labels? So at the top of your changelog, have an RST directive like:

.. changelog-role: major-bug
    :display-string: Bug
    :lines: minor

.. changelog-role: breaking-feature
    :display-string: Bug
    :lines: major

.. changelog-role: gui
    :display-string: GUI
    :lines: patch, minor, major
MinchinWeb commented 8 years ago

If we're talking breaking changes, would it make sense to be consistent with SemVer in the use of "major", "minor", and "patch"?

So if the project is currently at 1.2.0, :bug:major would be added to the 2.0.0 release, but not 1.3.0 or 1.2.1 (because 2.0.0 is the next "major" release).