search

bitprophet / releases

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

Add :info: role. #3

Closed keimlink closed 10 years ago

keimlink commented 11 years ago

Add a new :info: role. This role can be used for advices or other information. It will only be shown with a single release.

bitprophet commented 11 years ago

Can you elaborate on how these are different from 'Support' (which I've been using as a catchall "stuff changed that isn't directly API related" - doc/build process changes, etc)? Usually when I think "info" I think "backwards incompatible changes" or similar - but those are still changes and thus tend to map to a feature or bug ticket.

Put another way, what sort of information belongs in :info: entries, aren't doc/build/etc related, and aren't actually related to a ticket in one's ticket tracker?

keimlink commented 11 years ago

I needed a way to add additional information to the changelog. Sometimes I want to thank people in the changelog for the work they have done which is not related to a specific issue. Furthermore I used it for entries that had no issue attached to them when converting my changelog to releases. See the django-marcador changelog for examples. Maybe there is a better/simpler solution for this?

bitprophet commented 11 years ago

Right now, "no issue attached" entries can be left as straight up list-items with text in them and will be considered as "bug" types by default. (Prior to e07fc6b they aren't given any special formatting, and I think should thus work for all of your 'info' use cases; after, they get specifically styled as bugs, and become mostly useful for actual non-issue-attached bugs.)

This is still not as flexible as I'd like, so see #1 - I am figuring out how to make issue attachment totally optional while retaining ability to specify issue type. May require use of directives instead of roles.

keimlink commented 11 years ago

One problem with the "straight up list-items" is that they are only used for a bugfix release and never for a minor or major release. The reason is that the "major" and "backported" attributes are fixed. So they are no alternative to the ":info:" role.

I agree that a directive would offer more flexibility than the actual roles.

keimlink commented 11 years ago

Maybe the :info: role could replace "straight up list-items" feature? Therefore the role should get a new name and the [INFO] prefix should be removed. The result would be a better "straight up list-items" feature.

bitprophet commented 10 years ago

Superseded by #10