+1. As a consumer, I'd be more likely to read a "Migration" doc before a Changelog. I'd only look at the Changelog if I were curious how they implemented the fix. With the Migration doc, I'd expect to learn how to make my app work with the new version.
On Wed, Oct 7, 2015 at 11:38 AM, Dylan Millikin <dylan.milli...@gmail.com> wrote: > +1 I like the idea of a todo list of sorts. > > On Wed, Oct 7, 2015 at 5:18 PM, Marko Rodriguez <okramma...@gmail.com> > wrote: > > > Yes. This is a good idea. > > > > Marko. > > > > http://markorodriguez.com > > > > On Oct 7, 2015, at 8:55 AM, Matt Frantz <matthew.h.fra...@gmail.com> > > wrote: > > > > > I like the idea of creating "Migration" documents. Separate docs for > > > implementers and clients would probably make it easier to consume. > > > Refactoring the information as a "todo" list, rather than having it go > > > chronologically by when each JIRA ticket was resolved would make it > even > > > more developer-friendly. For example, here's the stuff you have to do > to > > > your structure classes. On the client side, here are the changes to > the > > > server interface, the Gremlin DSL changes organized by step, etc. > > > > > > On Wed, Oct 7, 2015 at 4:16 AM, Stephen Mallette <spmalle...@gmail.com > > > > > wrote: > > > > > >> 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 > > >>>>> > > >>>>> > > >>>> > > >>> > > >> > > > > > -- Have a good one, Jason
