+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 > >>>>> > >>>>> > >>>> > >>> > >> > >
