I'm going to resurrect this old-ish thread as we didn't really draw to any particular conclusion and new releases are looming. Just to save folks from having to re-read the thread itself, the basic summary is that we want to make it easy for implementers and users to consume our new releases. We largely rely on two things right now to convey that information:
1. JIRA and the "breaking" label 2. CHANGELOG (which is generated from JIRA) The idea is that people reading CHANGELOG check in on JIRA to see how to resolve their upgrade issues. I find two issues with that. First, I wouldn't like to do that if I were a user (i.e. resolving JIRA URLs to find out what's going on in a release). Second, we have no "document" that yields a nice summary of all change. We used to have a bit more verbosity in the CHANGELOG when it wasn't just JIRA, but even then it wasn't pretty and didn't provide much information on how to upgrade. I'd proposed the idea in this thread that we create a "companion" document in /docs to CHANGELOG. This document would be the thing we point folks to when we have a release and it roughly contains: 1. A summary of important/major changes. 2. A section for implementers that describes how to resolve "breaking" change 3. A section for users that describes how to resolve "breaking" change. Anyone like this idea? If not, are there other ideas on how we can improve here? On Wed, Sep 9, 2015 at 9:49 AM, Stephen Mallette <spmalle...@gmail.com> wrote: > I added a section about "Deprecation" to CONTRIBUTING that describes the > patterns we've been using informally: > > > https://github.com/apache/incubator-tinkerpop/blob/dd6bcfb6b23525863e1073e304f6a5aea0ca3c35/CONTRIBUTING.asciidoc#deprecation > > I added in one additional thing we haven't been doing: Creating JIRA > issues to track deprecated methods for future removal. It seems like that's > an easy way to not lose track of anything we deprecated (i.e. as soon as we > deprecate something - create a ticket in jira for future removal). We can > then periodically roll through those JIRA issues and have a community > discussion about when it is prudent to remove something for good. Sound > good? > > I replied to this thread as it related to "breaking" change and how we > convey it to folks. Haven't seen any more replies to this thread since - > any new ideas around breaking/changelog/etc? > > On Wed, Sep 2, 2015 at 4:53 PM, Stephen Mallette <spmalle...@gmail.com> > wrote: > >> 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 >>> >>> >> >
