The "breaking" label seems a bit too broad - especially after going through the details of the release process today. i do believe we need some additional categorization in there - especially for users who are trying to figure out what's going on when they bump version. i don't think we should shove it all into CHANGELOG though - i have the sense that for it to be useful we'll need more than just one-line bullets. For instance, take a look at what i just pushed into this issue as a comment:
https://issues.apache.org/jira/browse/TINKERPOP3-690?focusedCommentId=14727966&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14727966 I needed several sentences plus a link to make it easy for folks to know what to do. perhaps, we have a companion document in /docs for each version that describes what to expect with the release. in that way we can be more descriptive, better summarize JIRA tickets, create the sections you described and have room to expand as needed, etc. If we did it this way I don't think it would be terrible to keep our single "breaking" label in JIRA for our internal use, because on release day we'd roll through the breaking labels on that release and make sure they were summarized properly in the companion doc. On Wed, Sep 2, 2015 at 3:35 PM, Marko Rodriguez <okramma...@gmail.com> wrote: > Hi Stephen (cc: others), > > I think you had an email about this at some point, but I can't find it. So > I will just say what I think is cool and please correct me if there is > already a pattern in place. > > I think we should make a distinction between "breaking" change and > "deprecating" change. Next, in the CHANGELOG, when there is a > breaking/deprecating change we should tag it like this: > > * Simplified `SackValueStep` so it now supports both > `sack(function)` and sack(function).by()`. (*deprecating*) > > Then, at the bottom of the CHANGELOG (for that release) we have two > sections: Breaking Solutions and Deprecating Solutions. For the example > above. > > Deprecating Solutions > ------------------------------ > > * `GremlinTraversal.sack(function,string)` can be rewritten using > `GraphTraversal.sack(function).by(string)`. > > This way, we not only explicitly show people what is deprecated and what > is "broken," but also how to solve it. > > Perhaps this is taking it too far, but we could even have like: > > * deprecating/breaking graph system vendor > * deprecating/breaking graph language vendor > * deprecating/breaking user code > > Thoughts?, > Marko. > > http://markorodriguez.com > >
