You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tinkerpop.apache.org by Marko Rodriguez <ok...@gmail.com> on 2015/09/02 21:35:06 UTC
Breaking Changes CHANGELOG?
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
Re: Breaking Changes CHANGELOG?
Posted by Stephen Mallette <sp...@gmail.com>.
This change is now in tp30/master. I've deployed 3.0.2-SNAPSHOT docs for
review (which means that bin/publish-docs.sh is tested and good to go):
http://tinkerpop.incubator.apache.org/docs/3.0.2-SNAPSHOT/upgrade.html
I'd say that an important order of business right now is to get our 3.0.2
"upgrade documentation" in order. Please consider any changes you might
have done on 3.0.2 and update our document in the tp30 branch accordingly:
https://github.com/apache/incubator-tinkerpop/blob/tp30/docs/src/upgrade-release-3.0.x-incubating.asciidoc
I've also started a 3.1.0 upgrade doc in master - while less urgent, please
find a moment to update that as well:
https://github.com/apache/incubator-tinkerpop/blob/master/docs/src/upgrade-release-3.1.x-incubating.asciidoc
I was looking at 3.1.0 in jira - lots of good stuff in there. I imagine
there's much to put in that upgrade document around that. Note that you
have to do an advanced search to filter just what comes with 3.1.0...i used
the following to get it in case you're interested:
project = TINKERPOP3 AND fixVersion = 3.1.0-incubating AND fixVersion not
in (3.0.2-incubating, 3.0.1-incubating) ORDER BY priority DESC
Thanks for all the discussion and input on this. I think that this
addition to our document set is going to really be appreciated by folks.
It's also nice to know we have a patter for introducing new "documentation
types". All good!
On Mon, Oct 12, 2015 at 5:28 PM, Stephen Mallette <sp...@gmail.com>
wrote:
> I took a swipe at this, but after some thought given my previous attempt,
> i came up with something more straightforward that didn't have to touch a
> bunch of Daniel's pre-processor stuff. In fact, I think it works so easily
> that putting it into 3.0.2 wouldn't be a big deal at all. One entry to the
> pom gives us what we need:
>
>
> https://github.com/apache/incubator-tinkerpop/commit/12e339998b0024741a2cc18795f65ff43d70d467
>
> Basically I just generate an "upgrade book" from upgrade.asciidoc which is
> generated in the same fashion as our "reference book" from index.asciidoc.
> This pattern is nice because it means that anytime we have a new class of
> documentation it just means adding a new "book". So we could have a
> "tutorial book", a "developers book", etc. This also answers the question
> of continuity of a single "upgrade" document that you can just scroll
> through end-to-end like our docs because it will have a table of contents
> and all that. Check out my screenshot attached.
>
> Anyway, the best part for me is that this was a super easy change, doesn't
> threaten the stability of our doc generation process with new stuff and
> everything still deploys via publish-docs.sh.
>
> Any thoughts on this slightly revised approach?
>
>
>
> On Mon, Oct 12, 2015 at 3:31 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
>> Based on the feedback I've seen here, I'm going to move forward with
>> re-organizing the docs in the fashion I presented. I think that this is
>> going to represent a pretty large change to our documentation process and
>> as such, the work will be done in master to be part of 3.1.0. It might be
>> a little weird, but I think we should do the 3.0.2 release documentation in
>> master once this work is done - so stuff will be a little our of synch for
>> this next release, but going forward we'll have a good solid pattern to
>> follow.
>>
>> https://issues.apache.org/jira/browse/TINKERPOP3-883
>>
>> On Fri, Oct 9, 2015 at 8:20 AM, Dylan Millikin <dy...@gmail.com>
>> wrote:
>>
>>> That's looking good. I like how everything is separated for the different
>>> providers and users. Makes it quite easy to get the information we want.
>>>
>>> On Thu, Oct 8, 2015 at 8:32 PM, Stephen Mallette <sp...@gmail.com>
>>> wrote:
>>>
>>> > yes - the "Upgrading" sections would be about migration. I was
>>> thinking
>>> > that each release would get a single standalone document which would
>>> take
>>> > you from the previous version forward...so if i was at 3.0.0 and going
>>> to
>>> > 3.0.1 then i just need the 3.0.1 release doc. If I was going from
>>> 3.0.0 to
>>> > 3.0.5 i would need the cumulative docs from 3.0.1 to 3.0.5. If i were
>>> > going from 3.0.0 to 3.1.0 i think we would roll up all the changes from
>>> > 3.0.x into the 3.1.0 release doc and then add in any additional change.
>>> > That's kinda what we've been doing with CHANGELOG thus far.
>>> >
>>> > On Thu, Oct 8, 2015 at 2:26 PM, Matt Frantz <
>>> matthew.h.frantz@gmail.com>
>>> > wrote:
>>> >
>>> > > The "Migration" information would be in the "Updating" section?
>>> > >
>>> > > How would we track the stack of migrations from version N to N+1 to
>>> N+2?
>>> > > Would it grow like a single CHANGELOG, or would there be separate
>>> > > documents?
>>> > >
>>> > > On Thu, Oct 8, 2015 at 9:47 AM, Stephen Mallette <
>>> spmallette@gmail.com>
>>> > > wrote:
>>> > >
>>> > > > Since this idea was generally liked, I created a branch from tp30
>>> to
>>> > play
>>> > > > around with the idea:
>>> > > >
>>> > > > https://github.com/apache/incubator-tinkerpop/tree/tp30-docs
>>> > > >
>>> > > > Unfortunately it meant mucking with the dreaded doc generation
>>> system
>>> > (so
>>> > > > there goes an easy 3.0.2 release for me), but, anyway, here's what
>>> I
>>> > did
>>> > > in
>>> > > > this branch for everyone to review:
>>> > > >
>>> > > > 1. I moved our asciidoc reference documentation to docs/src/book
>>> > > > 2. I created docs/src/article
>>> > > > 3. In "article" we can add our "release documents"
>>> > > > 4. An "article" doesn't have to be just for "release documents" -
>>> in
>>> > > > essence it can be anything, but I think it should be something time
>>> > > related
>>> > > > and static.
>>> > > > 5. Why static? because i don't expect an "article" to change.
>>> Like, it
>>> > > is
>>> > > > meant to be a snapshot of how something is at a point in time (note
>>> > that
>>> > > > Daniel's pre-processor isn't hooked up to this for this reason)
>>> > > > 6. This opens up the possibility that we could also have other
>>> > > directories
>>> > > > with generated content. The idea to have "dev" immediately came to
>>> > mind
>>> > > to
>>> > > > house "developer documentation".
>>> > > >
>>> > > > As for the format of our "release document" I did this:
>>> > > >
>>> > > >
>>> > > >
>>> > >
>>> >
>>> https://github.com/apache/incubator-tinkerpop/blob/tp30-docs/docs/src/article/09162015-release-3.0.1-incubating.asciidoc
>>> > > >
>>> > > > You can do a bin/process-docs.sh --dryRun to generate the doc - it
>>> will
>>> > > > show up in target/docs/htmlsingle/ as a standalone html file. I
>>> guess
>>> > > once
>>> > > > that html gets uploaded to the website, we can choose to link to
>>> that
>>> > > > document directly from wherever as a standalone file.
>>> > > >
>>> > > > What do you all think - both of overall change and the "release
>>> > document"
>>> > > > format?
>>> > > >
>>> > > >
>>> > > >
>>> > > > On Wed, Oct 7, 2015 at 12:01 PM, Jason Plurad <pl...@gmail.com>
>>> > wrote:
>>> > > >
>>> > > > > +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.millikin@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 <
>>> > > okrammarko@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.frantz@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 <
>>> > > > > spmallette@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 <
>>> > > > > > spmallette@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 <
>>> > > > > > spmallette@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 <
>>> > > > > > okrammarko@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
>>> > > > >
>>> > > >
>>> > >
>>> >
>>>
>>
>>
>
Re: Breaking Changes CHANGELOG?
Posted by Stephen Mallette <sp...@gmail.com>.
I took a swipe at this, but after some thought given my previous attempt, i
came up with something more straightforward that didn't have to touch a
bunch of Daniel's pre-processor stuff. In fact, I think it works so easily
that putting it into 3.0.2 wouldn't be a big deal at all. One entry to the
pom gives us what we need:
https://github.com/apache/incubator-tinkerpop/commit/12e339998b0024741a2cc18795f65ff43d70d467
Basically I just generate an "upgrade book" from upgrade.asciidoc which is
generated in the same fashion as our "reference book" from index.asciidoc.
This pattern is nice because it means that anytime we have a new class of
documentation it just means adding a new "book". So we could have a
"tutorial book", a "developers book", etc. This also answers the question
of continuity of a single "upgrade" document that you can just scroll
through end-to-end like our docs because it will have a table of contents
and all that. Check out my screenshot attached.
Anyway, the best part for me is that this was a super easy change, doesn't
threaten the stability of our doc generation process with new stuff and
everything still deploys via publish-docs.sh.
Any thoughts on this slightly revised approach?
On Mon, Oct 12, 2015 at 3:31 PM, Stephen Mallette <sp...@gmail.com>
wrote:
> Based on the feedback I've seen here, I'm going to move forward with
> re-organizing the docs in the fashion I presented. I think that this is
> going to represent a pretty large change to our documentation process and
> as such, the work will be done in master to be part of 3.1.0. It might be
> a little weird, but I think we should do the 3.0.2 release documentation in
> master once this work is done - so stuff will be a little our of synch for
> this next release, but going forward we'll have a good solid pattern to
> follow.
>
> https://issues.apache.org/jira/browse/TINKERPOP3-883
>
> On Fri, Oct 9, 2015 at 8:20 AM, Dylan Millikin <dy...@gmail.com>
> wrote:
>
>> That's looking good. I like how everything is separated for the different
>> providers and users. Makes it quite easy to get the information we want.
>>
>> On Thu, Oct 8, 2015 at 8:32 PM, Stephen Mallette <sp...@gmail.com>
>> wrote:
>>
>> > yes - the "Upgrading" sections would be about migration. I was thinking
>> > that each release would get a single standalone document which would
>> take
>> > you from the previous version forward...so if i was at 3.0.0 and going
>> to
>> > 3.0.1 then i just need the 3.0.1 release doc. If I was going from
>> 3.0.0 to
>> > 3.0.5 i would need the cumulative docs from 3.0.1 to 3.0.5. If i were
>> > going from 3.0.0 to 3.1.0 i think we would roll up all the changes from
>> > 3.0.x into the 3.1.0 release doc and then add in any additional change.
>> > That's kinda what we've been doing with CHANGELOG thus far.
>> >
>> > On Thu, Oct 8, 2015 at 2:26 PM, Matt Frantz <matthew.h.frantz@gmail.com
>> >
>> > wrote:
>> >
>> > > The "Migration" information would be in the "Updating" section?
>> > >
>> > > How would we track the stack of migrations from version N to N+1 to
>> N+2?
>> > > Would it grow like a single CHANGELOG, or would there be separate
>> > > documents?
>> > >
>> > > On Thu, Oct 8, 2015 at 9:47 AM, Stephen Mallette <
>> spmallette@gmail.com>
>> > > wrote:
>> > >
>> > > > Since this idea was generally liked, I created a branch from tp30 to
>> > play
>> > > > around with the idea:
>> > > >
>> > > > https://github.com/apache/incubator-tinkerpop/tree/tp30-docs
>> > > >
>> > > > Unfortunately it meant mucking with the dreaded doc generation
>> system
>> > (so
>> > > > there goes an easy 3.0.2 release for me), but, anyway, here's what I
>> > did
>> > > in
>> > > > this branch for everyone to review:
>> > > >
>> > > > 1. I moved our asciidoc reference documentation to docs/src/book
>> > > > 2. I created docs/src/article
>> > > > 3. In "article" we can add our "release documents"
>> > > > 4. An "article" doesn't have to be just for "release documents" - in
>> > > > essence it can be anything, but I think it should be something time
>> > > related
>> > > > and static.
>> > > > 5. Why static? because i don't expect an "article" to change.
>> Like, it
>> > > is
>> > > > meant to be a snapshot of how something is at a point in time (note
>> > that
>> > > > Daniel's pre-processor isn't hooked up to this for this reason)
>> > > > 6. This opens up the possibility that we could also have other
>> > > directories
>> > > > with generated content. The idea to have "dev" immediately came to
>> > mind
>> > > to
>> > > > house "developer documentation".
>> > > >
>> > > > As for the format of our "release document" I did this:
>> > > >
>> > > >
>> > > >
>> > >
>> >
>> https://github.com/apache/incubator-tinkerpop/blob/tp30-docs/docs/src/article/09162015-release-3.0.1-incubating.asciidoc
>> > > >
>> > > > You can do a bin/process-docs.sh --dryRun to generate the doc - it
>> will
>> > > > show up in target/docs/htmlsingle/ as a standalone html file. I
>> guess
>> > > once
>> > > > that html gets uploaded to the website, we can choose to link to
>> that
>> > > > document directly from wherever as a standalone file.
>> > > >
>> > > > What do you all think - both of overall change and the "release
>> > document"
>> > > > format?
>> > > >
>> > > >
>> > > >
>> > > > On Wed, Oct 7, 2015 at 12:01 PM, Jason Plurad <pl...@gmail.com>
>> > wrote:
>> > > >
>> > > > > +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.millikin@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 <
>> > > okrammarko@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.frantz@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 <
>> > > > > spmallette@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 <
>> > > > > > spmallette@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 <
>> > > > > > spmallette@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 <
>> > > > > > okrammarko@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
>> > > > >
>> > > >
>> > >
>> >
>>
>
>
Re: Breaking Changes CHANGELOG?
Posted by Stephen Mallette <sp...@gmail.com>.
Based on the feedback I've seen here, I'm going to move forward with
re-organizing the docs in the fashion I presented. I think that this is
going to represent a pretty large change to our documentation process and
as such, the work will be done in master to be part of 3.1.0. It might be
a little weird, but I think we should do the 3.0.2 release documentation in
master once this work is done - so stuff will be a little our of synch for
this next release, but going forward we'll have a good solid pattern to
follow.
https://issues.apache.org/jira/browse/TINKERPOP3-883
On Fri, Oct 9, 2015 at 8:20 AM, Dylan Millikin <dy...@gmail.com>
wrote:
> That's looking good. I like how everything is separated for the different
> providers and users. Makes it quite easy to get the information we want.
>
> On Thu, Oct 8, 2015 at 8:32 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > yes - the "Upgrading" sections would be about migration. I was thinking
> > that each release would get a single standalone document which would take
> > you from the previous version forward...so if i was at 3.0.0 and going to
> > 3.0.1 then i just need the 3.0.1 release doc. If I was going from 3.0.0
> to
> > 3.0.5 i would need the cumulative docs from 3.0.1 to 3.0.5. If i were
> > going from 3.0.0 to 3.1.0 i think we would roll up all the changes from
> > 3.0.x into the 3.1.0 release doc and then add in any additional change.
> > That's kinda what we've been doing with CHANGELOG thus far.
> >
> > On Thu, Oct 8, 2015 at 2:26 PM, Matt Frantz <ma...@gmail.com>
> > wrote:
> >
> > > The "Migration" information would be in the "Updating" section?
> > >
> > > How would we track the stack of migrations from version N to N+1 to
> N+2?
> > > Would it grow like a single CHANGELOG, or would there be separate
> > > documents?
> > >
> > > On Thu, Oct 8, 2015 at 9:47 AM, Stephen Mallette <spmallette@gmail.com
> >
> > > wrote:
> > >
> > > > Since this idea was generally liked, I created a branch from tp30 to
> > play
> > > > around with the idea:
> > > >
> > > > https://github.com/apache/incubator-tinkerpop/tree/tp30-docs
> > > >
> > > > Unfortunately it meant mucking with the dreaded doc generation system
> > (so
> > > > there goes an easy 3.0.2 release for me), but, anyway, here's what I
> > did
> > > in
> > > > this branch for everyone to review:
> > > >
> > > > 1. I moved our asciidoc reference documentation to docs/src/book
> > > > 2. I created docs/src/article
> > > > 3. In "article" we can add our "release documents"
> > > > 4. An "article" doesn't have to be just for "release documents" - in
> > > > essence it can be anything, but I think it should be something time
> > > related
> > > > and static.
> > > > 5. Why static? because i don't expect an "article" to change. Like,
> it
> > > is
> > > > meant to be a snapshot of how something is at a point in time (note
> > that
> > > > Daniel's pre-processor isn't hooked up to this for this reason)
> > > > 6. This opens up the possibility that we could also have other
> > > directories
> > > > with generated content. The idea to have "dev" immediately came to
> > mind
> > > to
> > > > house "developer documentation".
> > > >
> > > > As for the format of our "release document" I did this:
> > > >
> > > >
> > > >
> > >
> >
> https://github.com/apache/incubator-tinkerpop/blob/tp30-docs/docs/src/article/09162015-release-3.0.1-incubating.asciidoc
> > > >
> > > > You can do a bin/process-docs.sh --dryRun to generate the doc - it
> will
> > > > show up in target/docs/htmlsingle/ as a standalone html file. I
> guess
> > > once
> > > > that html gets uploaded to the website, we can choose to link to that
> > > > document directly from wherever as a standalone file.
> > > >
> > > > What do you all think - both of overall change and the "release
> > document"
> > > > format?
> > > >
> > > >
> > > >
> > > > On Wed, Oct 7, 2015 at 12:01 PM, Jason Plurad <pl...@gmail.com>
> > wrote:
> > > >
> > > > > +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.millikin@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 <
> > > okrammarko@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.frantz@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 <
> > > > > spmallette@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 <
> > > > > > spmallette@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 <
> > > > > > spmallette@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 <
> > > > > > okrammarko@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
> > > > >
> > > >
> > >
> >
>
Re: Breaking Changes CHANGELOG?
Posted by Dylan Millikin <dy...@gmail.com>.
That's looking good. I like how everything is separated for the different
providers and users. Makes it quite easy to get the information we want.
On Thu, Oct 8, 2015 at 8:32 PM, Stephen Mallette <sp...@gmail.com>
wrote:
> yes - the "Upgrading" sections would be about migration. I was thinking
> that each release would get a single standalone document which would take
> you from the previous version forward...so if i was at 3.0.0 and going to
> 3.0.1 then i just need the 3.0.1 release doc. If I was going from 3.0.0 to
> 3.0.5 i would need the cumulative docs from 3.0.1 to 3.0.5. If i were
> going from 3.0.0 to 3.1.0 i think we would roll up all the changes from
> 3.0.x into the 3.1.0 release doc and then add in any additional change.
> That's kinda what we've been doing with CHANGELOG thus far.
>
> On Thu, Oct 8, 2015 at 2:26 PM, Matt Frantz <ma...@gmail.com>
> wrote:
>
> > The "Migration" information would be in the "Updating" section?
> >
> > How would we track the stack of migrations from version N to N+1 to N+2?
> > Would it grow like a single CHANGELOG, or would there be separate
> > documents?
> >
> > On Thu, Oct 8, 2015 at 9:47 AM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> >
> > > Since this idea was generally liked, I created a branch from tp30 to
> play
> > > around with the idea:
> > >
> > > https://github.com/apache/incubator-tinkerpop/tree/tp30-docs
> > >
> > > Unfortunately it meant mucking with the dreaded doc generation system
> (so
> > > there goes an easy 3.0.2 release for me), but, anyway, here's what I
> did
> > in
> > > this branch for everyone to review:
> > >
> > > 1. I moved our asciidoc reference documentation to docs/src/book
> > > 2. I created docs/src/article
> > > 3. In "article" we can add our "release documents"
> > > 4. An "article" doesn't have to be just for "release documents" - in
> > > essence it can be anything, but I think it should be something time
> > related
> > > and static.
> > > 5. Why static? because i don't expect an "article" to change. Like, it
> > is
> > > meant to be a snapshot of how something is at a point in time (note
> that
> > > Daniel's pre-processor isn't hooked up to this for this reason)
> > > 6. This opens up the possibility that we could also have other
> > directories
> > > with generated content. The idea to have "dev" immediately came to
> mind
> > to
> > > house "developer documentation".
> > >
> > > As for the format of our "release document" I did this:
> > >
> > >
> > >
> >
> https://github.com/apache/incubator-tinkerpop/blob/tp30-docs/docs/src/article/09162015-release-3.0.1-incubating.asciidoc
> > >
> > > You can do a bin/process-docs.sh --dryRun to generate the doc - it will
> > > show up in target/docs/htmlsingle/ as a standalone html file. I guess
> > once
> > > that html gets uploaded to the website, we can choose to link to that
> > > document directly from wherever as a standalone file.
> > >
> > > What do you all think - both of overall change and the "release
> document"
> > > format?
> > >
> > >
> > >
> > > On Wed, Oct 7, 2015 at 12:01 PM, Jason Plurad <pl...@gmail.com>
> wrote:
> > >
> > > > +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.millikin@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 <
> > okrammarko@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.frantz@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 <
> > > > spmallette@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 <
> > > > > spmallette@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 <
> > > > > spmallette@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 <
> > > > > okrammarko@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
> > > >
> > >
> >
>
Re: Breaking Changes CHANGELOG?
Posted by Stephen Mallette <sp...@gmail.com>.
yes - the "Upgrading" sections would be about migration. I was thinking
that each release would get a single standalone document which would take
you from the previous version forward...so if i was at 3.0.0 and going to
3.0.1 then i just need the 3.0.1 release doc. If I was going from 3.0.0 to
3.0.5 i would need the cumulative docs from 3.0.1 to 3.0.5. If i were
going from 3.0.0 to 3.1.0 i think we would roll up all the changes from
3.0.x into the 3.1.0 release doc and then add in any additional change.
That's kinda what we've been doing with CHANGELOG thus far.
On Thu, Oct 8, 2015 at 2:26 PM, Matt Frantz <ma...@gmail.com>
wrote:
> The "Migration" information would be in the "Updating" section?
>
> How would we track the stack of migrations from version N to N+1 to N+2?
> Would it grow like a single CHANGELOG, or would there be separate
> documents?
>
> On Thu, Oct 8, 2015 at 9:47 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > Since this idea was generally liked, I created a branch from tp30 to play
> > around with the idea:
> >
> > https://github.com/apache/incubator-tinkerpop/tree/tp30-docs
> >
> > Unfortunately it meant mucking with the dreaded doc generation system (so
> > there goes an easy 3.0.2 release for me), but, anyway, here's what I did
> in
> > this branch for everyone to review:
> >
> > 1. I moved our asciidoc reference documentation to docs/src/book
> > 2. I created docs/src/article
> > 3. In "article" we can add our "release documents"
> > 4. An "article" doesn't have to be just for "release documents" - in
> > essence it can be anything, but I think it should be something time
> related
> > and static.
> > 5. Why static? because i don't expect an "article" to change. Like, it
> is
> > meant to be a snapshot of how something is at a point in time (note that
> > Daniel's pre-processor isn't hooked up to this for this reason)
> > 6. This opens up the possibility that we could also have other
> directories
> > with generated content. The idea to have "dev" immediately came to mind
> to
> > house "developer documentation".
> >
> > As for the format of our "release document" I did this:
> >
> >
> >
> https://github.com/apache/incubator-tinkerpop/blob/tp30-docs/docs/src/article/09162015-release-3.0.1-incubating.asciidoc
> >
> > You can do a bin/process-docs.sh --dryRun to generate the doc - it will
> > show up in target/docs/htmlsingle/ as a standalone html file. I guess
> once
> > that html gets uploaded to the website, we can choose to link to that
> > document directly from wherever as a standalone file.
> >
> > What do you all think - both of overall change and the "release document"
> > format?
> >
> >
> >
> > On Wed, Oct 7, 2015 at 12:01 PM, Jason Plurad <pl...@gmail.com> wrote:
> >
> > > +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.millikin@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 <
> okrammarko@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.frantz@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 <
> > > spmallette@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 <
> > > > spmallette@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 <
> > > > spmallette@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 <
> > > > okrammarko@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
> > >
> >
>
Re: Breaking Changes CHANGELOG?
Posted by Matt Frantz <ma...@gmail.com>.
The "Migration" information would be in the "Updating" section?
How would we track the stack of migrations from version N to N+1 to N+2?
Would it grow like a single CHANGELOG, or would there be separate documents?
On Thu, Oct 8, 2015 at 9:47 AM, Stephen Mallette <sp...@gmail.com>
wrote:
> Since this idea was generally liked, I created a branch from tp30 to play
> around with the idea:
>
> https://github.com/apache/incubator-tinkerpop/tree/tp30-docs
>
> Unfortunately it meant mucking with the dreaded doc generation system (so
> there goes an easy 3.0.2 release for me), but, anyway, here's what I did in
> this branch for everyone to review:
>
> 1. I moved our asciidoc reference documentation to docs/src/book
> 2. I created docs/src/article
> 3. In "article" we can add our "release documents"
> 4. An "article" doesn't have to be just for "release documents" - in
> essence it can be anything, but I think it should be something time related
> and static.
> 5. Why static? because i don't expect an "article" to change. Like, it is
> meant to be a snapshot of how something is at a point in time (note that
> Daniel's pre-processor isn't hooked up to this for this reason)
> 6. This opens up the possibility that we could also have other directories
> with generated content. The idea to have "dev" immediately came to mind to
> house "developer documentation".
>
> As for the format of our "release document" I did this:
>
>
> https://github.com/apache/incubator-tinkerpop/blob/tp30-docs/docs/src/article/09162015-release-3.0.1-incubating.asciidoc
>
> You can do a bin/process-docs.sh --dryRun to generate the doc - it will
> show up in target/docs/htmlsingle/ as a standalone html file. I guess once
> that html gets uploaded to the website, we can choose to link to that
> document directly from wherever as a standalone file.
>
> What do you all think - both of overall change and the "release document"
> format?
>
>
>
> On Wed, Oct 7, 2015 at 12:01 PM, Jason Plurad <pl...@gmail.com> wrote:
>
> > +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.millikin@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 <ok...@gmail.com>
> > > wrote:
> > >
> > > > Yes. This is a good idea.
> > > >
> > > > Marko.
> > > >
> > > > http://markorodriguez.com
> > > >
> > > > On Oct 7, 2015, at 8:55 AM, Matt Frantz <ma...@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 <
> > spmallette@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 <
> > > spmallette@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 <
> > > spmallette@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 <
> > > okrammarko@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
> >
>
Re: Breaking Changes CHANGELOG?
Posted by Stephen Mallette <sp...@gmail.com>.
Since this idea was generally liked, I created a branch from tp30 to play
around with the idea:
https://github.com/apache/incubator-tinkerpop/tree/tp30-docs
Unfortunately it meant mucking with the dreaded doc generation system (so
there goes an easy 3.0.2 release for me), but, anyway, here's what I did in
this branch for everyone to review:
1. I moved our asciidoc reference documentation to docs/src/book
2. I created docs/src/article
3. In "article" we can add our "release documents"
4. An "article" doesn't have to be just for "release documents" - in
essence it can be anything, but I think it should be something time related
and static.
5. Why static? because i don't expect an "article" to change. Like, it is
meant to be a snapshot of how something is at a point in time (note that
Daniel's pre-processor isn't hooked up to this for this reason)
6. This opens up the possibility that we could also have other directories
with generated content. The idea to have "dev" immediately came to mind to
house "developer documentation".
As for the format of our "release document" I did this:
https://github.com/apache/incubator-tinkerpop/blob/tp30-docs/docs/src/article/09162015-release-3.0.1-incubating.asciidoc
You can do a bin/process-docs.sh --dryRun to generate the doc - it will
show up in target/docs/htmlsingle/ as a standalone html file. I guess once
that html gets uploaded to the website, we can choose to link to that
document directly from wherever as a standalone file.
What do you all think - both of overall change and the "release document"
format?
On Wed, Oct 7, 2015 at 12:01 PM, Jason Plurad <pl...@gmail.com> wrote:
> +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 <dy...@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 <ok...@gmail.com>
> > wrote:
> >
> > > Yes. This is a good idea.
> > >
> > > Marko.
> > >
> > > http://markorodriguez.com
> > >
> > > On Oct 7, 2015, at 8:55 AM, Matt Frantz <ma...@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 <
> spmallette@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 <
> > spmallette@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 <
> > spmallette@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 <
> > okrammarko@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
>
Re: Breaking Changes CHANGELOG?
Posted by Jason Plurad <pl...@gmail.com>.
+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 <dy...@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 <ok...@gmail.com>
> wrote:
>
> > Yes. This is a good idea.
> >
> > Marko.
> >
> > http://markorodriguez.com
> >
> > On Oct 7, 2015, at 8:55 AM, Matt Frantz <ma...@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 <spmallette@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 <
> spmallette@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 <
> spmallette@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 <
> okrammarko@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
Re: Breaking Changes CHANGELOG?
Posted by Dylan Millikin <dy...@gmail.com>.
+1 I like the idea of a todo list of sorts.
On Wed, Oct 7, 2015 at 5:18 PM, Marko Rodriguez <ok...@gmail.com>
wrote:
> Yes. This is a good idea.
>
> Marko.
>
> http://markorodriguez.com
>
> On Oct 7, 2015, at 8:55 AM, Matt Frantz <ma...@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 <sp...@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 <sp...@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 <spmallette@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 <okrammarko@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
> >>>>>
> >>>>>
> >>>>
> >>>
> >>
>
>
Re: Breaking Changes CHANGELOG?
Posted by Marko Rodriguez <ok...@gmail.com>.
Yes. This is a good idea.
Marko.
http://markorodriguez.com
On Oct 7, 2015, at 8:55 AM, Matt Frantz <ma...@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 <sp...@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 <sp...@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 <sp...@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 <ok...@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
>>>>>
>>>>>
>>>>
>>>
>>
Re: Breaking Changes CHANGELOG?
Posted by Matt Frantz <ma...@gmail.com>.
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 <sp...@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 <sp...@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 <sp...@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 <ok...@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
> >>>
> >>>
> >>
> >
>
Re: Breaking Changes CHANGELOG?
Posted by Stephen Mallette <sp...@gmail.com>.
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 <sp...@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 <sp...@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 <ok...@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
>>>
>>>
>>
>
Re: Breaking Changes CHANGELOG?
Posted by Stephen Mallette <sp...@gmail.com>.
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 <sp...@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 <ok...@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
>>
>>
>
Re: Breaking Changes CHANGELOG?
Posted by Stephen Mallette <sp...@gmail.com>.
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 <ok...@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
>
>