branching after GA

[Stephen Mallette <sp...@gmail.com>]

I think it's worthwhile for us to do something we've not really done before
with any of the TinkerPop projects: use branches. We typically tend to use
branches for major refactoring that we might throw out, but not really for
release management. As we look past release 3.0.0, I think we will want to
have the capability to do more frequent minor releases (e.g. 3.0.1, 3.0.2,
etc) while still being able to do work for a future 3.1.x line of code.

I think we can do this without too much change if we introduce a simple
branch system.  Release branch rules would be simple - we create a new
branch from master called tp31 for the 3.1.x line of code.  Any changes
that are "breaking", introduce significant risk, a "major" feature, etc.
would be committed there.  All other changes, bug fixes, non-breaking
refactoring of major APIs, "minor" features, etc. would simply commit to
master.  the master branch effectively becomes the 3.0.x line of code.
Under this approach the merge process is pretty simple in that we just
merge forward (i.e. master merges to to tp31).

When the day comes that we're ready to release 3.1.0, we merge tp31 back to
master and create tp32 and use the same model where the 3.1.x line is
master and the 3.2.x line is tp32.  Of course, under this model we are
really supporting just the previous minor version, which for right now
seems acceptable to me.  That's more than what we've ever really done well,
so that feels like a good starting point in my book.  After we release
3.1.0 we can revisit and decide if a more complex branching strategy is
needed.

Re: branching after GA

[Marko Rodriguez <ok...@gmail.com>]

Excellent. This makes sense to me. 

Thank you,
Marko.

http://markorodriguez.com

On Jul 14, 2015, at 5:05 AM, Stephen Mallette <sp...@gmail.com> wrote:

> I've created the tp30 branch starting at tags/3.0.0-incubating and set the
> version at 3.0.1-SNAPSHOT. "master" is at 3.1.0-SNAPSHOT.  Note that I've
> also created versions 3.0.1-incubating and 3.1.0-incubating in jira.
> 
> On Mon, Jul 13, 2015 at 2:27 PM, Matt Frantz <ma...@gmail.com>
> wrote:
> 
>> Makes sense to me.
>> 
>> On Mon, Jul 13, 2015 at 11:03 AM, Stephen Mallette <sp...@gmail.com>
>> wrote:
>> 
>>> Thanks for your thoughts Matt....I'm ok with that model as well.  Under
>>> that model, we would create tp30 to maintain the 3.0.x line then commit
>>> everything else to master (which would be the 3.1.x line), merging back
>> to
>>> master from tp30 as needed.  In suggesting the approach that I did, I
>> guess
>>> I sorta thought that the place "where most people are
>>> working" post-GA would be the 3.0.x line.  I think we would be looking to
>>> avoid breaking change in the immediate term, so 3.0.x==master made sense
>> to
>>> me.
>>> 
>>> 
>>> 
>>> On Mon, Jul 13, 2015 at 1:45 PM, Matt Frantz <matthew.h.frantz@gmail.com
>>> 
>>> wrote:
>>> 
>>>> +1
>>>> 
>>>> A roughly symmetric branching strategy would assign the master branch
>> to
>>>> the role of "where most people are working".  Release branches, e.g.
>>> 3.0.0,
>>>> would be created when we "feature freeze" them.  Bug fixes go there,
>> and
>>>> those release branches are periodically merged to master.  When
>>> development
>>>> stops, those branches can be tagged and deleted.
>>>> 
>>>> On Mon, Jul 13, 2015 at 4:20 AM, Stephen Mallette <
>> spmallette@gmail.com>
>>>> wrote:
>>>> 
>>>>> I think it's worthwhile for us to do something we've not really done
>>>> before
>>>>> with any of the TinkerPop projects: use branches. We typically tend
>> to
>>>> use
>>>>> branches for major refactoring that we might throw out, but not
>> really
>>>> for
>>>>> release management. As we look past release 3.0.0, I think we will
>> want
>>>> to
>>>>> have the capability to do more frequent minor releases (e.g. 3.0.1,
>>>> 3.0.2,
>>>>> etc) while still being able to do work for a future 3.1.x line of
>> code.
>>>>> 
>>>>> I think we can do this without too much change if we introduce a
>> simple
>>>>> branch system.  Release branch rules would be simple - we create a
>> new
>>>>> branch from master called tp31 for the 3.1.x line of code.  Any
>> changes
>>>>> that are "breaking", introduce significant risk, a "major" feature,
>>> etc.
>>>>> would be committed there.  All other changes, bug fixes, non-breaking
>>>>> refactoring of major APIs, "minor" features, etc. would simply commit
>>> to
>>>>> master.  the master branch effectively becomes the 3.0.x line of
>> code.
>>>>> Under this approach the merge process is pretty simple in that we
>> just
>>>>> merge forward (i.e. master merges to to tp31).
>>>>> 
>>>>> When the day comes that we're ready to release 3.1.0, we merge tp31
>>> back
>>>> to
>>>>> master and create tp32 and use the same model where the 3.1.x line is
>>>>> master and the 3.2.x line is tp32.  Of course, under this model we
>> are
>>>>> really supporting just the previous minor version, which for right
>> now
>>>>> seems acceptable to me.  That's more than what we've ever really done
>>>> well,
>>>>> so that feels like a good starting point in my book.  After we
>> release
>>>>> 3.1.0 we can revisit and decide if a more complex branching strategy
>> is
>>>>> needed.
>>>>> 
>>>> 
>>> 
>> 

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

I've created the tp30 branch starting at tags/3.0.0-incubating and set the
version at 3.0.1-SNAPSHOT. "master" is at 3.1.0-SNAPSHOT.  Note that I've
also created versions 3.0.1-incubating and 3.1.0-incubating in jira.

On Mon, Jul 13, 2015 at 2:27 PM, Matt Frantz <ma...@gmail.com>
wrote:

> Makes sense to me.
>
> On Mon, Jul 13, 2015 at 11:03 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > Thanks for your thoughts Matt....I'm ok with that model as well.  Under
> > that model, we would create tp30 to maintain the 3.0.x line then commit
> > everything else to master (which would be the 3.1.x line), merging back
> to
> > master from tp30 as needed.  In suggesting the approach that I did, I
> guess
> > I sorta thought that the place "where most people are
> > working" post-GA would be the 3.0.x line.  I think we would be looking to
> > avoid breaking change in the immediate term, so 3.0.x==master made sense
> to
> > me.
> >
> >
> >
> > On Mon, Jul 13, 2015 at 1:45 PM, Matt Frantz <matthew.h.frantz@gmail.com
> >
> > wrote:
> >
> > > +1
> > >
> > > A roughly symmetric branching strategy would assign the master branch
> to
> > > the role of "where most people are working".  Release branches, e.g.
> > 3.0.0,
> > > would be created when we "feature freeze" them.  Bug fixes go there,
> and
> > > those release branches are periodically merged to master.  When
> > development
> > > stops, those branches can be tagged and deleted.
> > >
> > > On Mon, Jul 13, 2015 at 4:20 AM, Stephen Mallette <
> spmallette@gmail.com>
> > > wrote:
> > >
> > > > I think it's worthwhile for us to do something we've not really done
> > > before
> > > > with any of the TinkerPop projects: use branches. We typically tend
> to
> > > use
> > > > branches for major refactoring that we might throw out, but not
> really
> > > for
> > > > release management. As we look past release 3.0.0, I think we will
> want
> > > to
> > > > have the capability to do more frequent minor releases (e.g. 3.0.1,
> > > 3.0.2,
> > > > etc) while still being able to do work for a future 3.1.x line of
> code.
> > > >
> > > > I think we can do this without too much change if we introduce a
> simple
> > > > branch system.  Release branch rules would be simple - we create a
> new
> > > > branch from master called tp31 for the 3.1.x line of code.  Any
> changes
> > > > that are "breaking", introduce significant risk, a "major" feature,
> > etc.
> > > > would be committed there.  All other changes, bug fixes, non-breaking
> > > > refactoring of major APIs, "minor" features, etc. would simply commit
> > to
> > > > master.  the master branch effectively becomes the 3.0.x line of
> code.
> > > > Under this approach the merge process is pretty simple in that we
> just
> > > > merge forward (i.e. master merges to to tp31).
> > > >
> > > > When the day comes that we're ready to release 3.1.0, we merge tp31
> > back
> > > to
> > > > master and create tp32 and use the same model where the 3.1.x line is
> > > > master and the 3.2.x line is tp32.  Of course, under this model we
> are
> > > > really supporting just the previous minor version, which for right
> now
> > > > seems acceptable to me.  That's more than what we've ever really done
> > > well,
> > > > so that feels like a good starting point in my book.  After we
> release
> > > > 3.1.0 we can revisit and decide if a more complex branching strategy
> is
> > > > needed.
> > > >
> > >
> >
>

Re: branching after GA

[Matt Frantz <ma...@gmail.com>]

Makes sense to me.

On Mon, Jul 13, 2015 at 11:03 AM, Stephen Mallette <sp...@gmail.com>
wrote:

> Thanks for your thoughts Matt....I'm ok with that model as well.  Under
> that model, we would create tp30 to maintain the 3.0.x line then commit
> everything else to master (which would be the 3.1.x line), merging back to
> master from tp30 as needed.  In suggesting the approach that I did, I guess
> I sorta thought that the place "where most people are
> working" post-GA would be the 3.0.x line.  I think we would be looking to
> avoid breaking change in the immediate term, so 3.0.x==master made sense to
> me.
>
>
>
> On Mon, Jul 13, 2015 at 1:45 PM, Matt Frantz <ma...@gmail.com>
> wrote:
>
> > +1
> >
> > A roughly symmetric branching strategy would assign the master branch to
> > the role of "where most people are working".  Release branches, e.g.
> 3.0.0,
> > would be created when we "feature freeze" them.  Bug fixes go there, and
> > those release branches are periodically merged to master.  When
> development
> > stops, those branches can be tagged and deleted.
> >
> > On Mon, Jul 13, 2015 at 4:20 AM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> >
> > > I think it's worthwhile for us to do something we've not really done
> > before
> > > with any of the TinkerPop projects: use branches. We typically tend to
> > use
> > > branches for major refactoring that we might throw out, but not really
> > for
> > > release management. As we look past release 3.0.0, I think we will want
> > to
> > > have the capability to do more frequent minor releases (e.g. 3.0.1,
> > 3.0.2,
> > > etc) while still being able to do work for a future 3.1.x line of code.
> > >
> > > I think we can do this without too much change if we introduce a simple
> > > branch system.  Release branch rules would be simple - we create a new
> > > branch from master called tp31 for the 3.1.x line of code.  Any changes
> > > that are "breaking", introduce significant risk, a "major" feature,
> etc.
> > > would be committed there.  All other changes, bug fixes, non-breaking
> > > refactoring of major APIs, "minor" features, etc. would simply commit
> to
> > > master.  the master branch effectively becomes the 3.0.x line of code.
> > > Under this approach the merge process is pretty simple in that we just
> > > merge forward (i.e. master merges to to tp31).
> > >
> > > When the day comes that we're ready to release 3.1.0, we merge tp31
> back
> > to
> > > master and create tp32 and use the same model where the 3.1.x line is
> > > master and the 3.2.x line is tp32.  Of course, under this model we are
> > > really supporting just the previous minor version, which for right now
> > > seems acceptable to me.  That's more than what we've ever really done
> > well,
> > > so that feels like a good starting point in my book.  After we release
> > > 3.1.0 we can revisit and decide if a more complex branching strategy is
> > > needed.
> > >
> >
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

Thanks for your thoughts Matt....I'm ok with that model as well.  Under
that model, we would create tp30 to maintain the 3.0.x line then commit
everything else to master (which would be the 3.1.x line), merging back to
master from tp30 as needed.  In suggesting the approach that I did, I guess
I sorta thought that the place "where most people are
working" post-GA would be the 3.0.x line.  I think we would be looking to
avoid breaking change in the immediate term, so 3.0.x==master made sense to
me.



On Mon, Jul 13, 2015 at 1:45 PM, Matt Frantz <ma...@gmail.com>
wrote:

> +1
>
> A roughly symmetric branching strategy would assign the master branch to
> the role of "where most people are working".  Release branches, e.g. 3.0.0,
> would be created when we "feature freeze" them.  Bug fixes go there, and
> those release branches are periodically merged to master.  When development
> stops, those branches can be tagged and deleted.
>
> On Mon, Jul 13, 2015 at 4:20 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > I think it's worthwhile for us to do something we've not really done
> before
> > with any of the TinkerPop projects: use branches. We typically tend to
> use
> > branches for major refactoring that we might throw out, but not really
> for
> > release management. As we look past release 3.0.0, I think we will want
> to
> > have the capability to do more frequent minor releases (e.g. 3.0.1,
> 3.0.2,
> > etc) while still being able to do work for a future 3.1.x line of code.
> >
> > I think we can do this without too much change if we introduce a simple
> > branch system.  Release branch rules would be simple - we create a new
> > branch from master called tp31 for the 3.1.x line of code.  Any changes
> > that are "breaking", introduce significant risk, a "major" feature, etc.
> > would be committed there.  All other changes, bug fixes, non-breaking
> > refactoring of major APIs, "minor" features, etc. would simply commit to
> > master.  the master branch effectively becomes the 3.0.x line of code.
> > Under this approach the merge process is pretty simple in that we just
> > merge forward (i.e. master merges to to tp31).
> >
> > When the day comes that we're ready to release 3.1.0, we merge tp31 back
> to
> > master and create tp32 and use the same model where the 3.1.x line is
> > master and the 3.2.x line is tp32.  Of course, under this model we are
> > really supporting just the previous minor version, which for right now
> > seems acceptable to me.  That's more than what we've ever really done
> well,
> > so that feels like a good starting point in my book.  After we release
> > 3.1.0 we can revisit and decide if a more complex branching strategy is
> > needed.
> >
>

Re: branching after GA

[Matt Frantz <ma...@gmail.com>]

+1

A roughly symmetric branching strategy would assign the master branch to
the role of "where most people are working".  Release branches, e.g. 3.0.0,
would be created when we "feature freeze" them.  Bug fixes go there, and
those release branches are periodically merged to master.  When development
stops, those branches can be tagged and deleted.

On Mon, Jul 13, 2015 at 4:20 AM, Stephen Mallette <sp...@gmail.com>
wrote:

> I think it's worthwhile for us to do something we've not really done before
> with any of the TinkerPop projects: use branches. We typically tend to use
> branches for major refactoring that we might throw out, but not really for
> release management. As we look past release 3.0.0, I think we will want to
> have the capability to do more frequent minor releases (e.g. 3.0.1, 3.0.2,
> etc) while still being able to do work for a future 3.1.x line of code.
>
> I think we can do this without too much change if we introduce a simple
> branch system.  Release branch rules would be simple - we create a new
> branch from master called tp31 for the 3.1.x line of code.  Any changes
> that are "breaking", introduce significant risk, a "major" feature, etc.
> would be committed there.  All other changes, bug fixes, non-breaking
> refactoring of major APIs, "minor" features, etc. would simply commit to
> master.  the master branch effectively becomes the 3.0.x line of code.
> Under this approach the merge process is pretty simple in that we just
> merge forward (i.e. master merges to to tp31).
>
> When the day comes that we're ready to release 3.1.0, we merge tp31 back to
> master and create tp32 and use the same model where the 3.1.x line is
> master and the 3.2.x line is tp32.  Of course, under this model we are
> really supporting just the previous minor version, which for right now
> seems acceptable to me.  That's more than what we've ever really done well,
> so that feels like a good starting point in my book.  After we release
> 3.1.0 we can revisit and decide if a more complex branching strategy is
> needed.
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

Ok - made some adjustments here.  Full build/test/ide stuff is here now:

https://github.com/apache/incubator-tinkerpop/blob/da57f391905542345b92e52634dcd72dfc4cdcff/CONTRIBUTING.asciidoc

The release process is here:

https://github.com/apache/incubator-tinkerpop/blob/da57f391905542345b92e52634dcd72dfc4cdcff/RELEASE.asciidoc

And the README now looks like this:

https://github.com/apache/incubator-tinkerpop/blob/f4eb36e9a2f08a95c631ba58c64a27857b005440/README.asciidoc

Any adjustments or changes to these should probably be made in the tp30
branch and merged back to master.



On Mon, Aug 10, 2015 at 11:14 AM, Marko Rodriguez <ok...@gmail.com>
wrote:

> > maybe we fix up the README to be a bit more user focused and do a little
> > better with project description and "getting started" as part of this
> > change.  i kinda feel like CONTRIBUTING is a better place for the deep
> > details of the build commands/options plus intellij setup...thoughts on
> > that?
>
> I concur.
>
> Marko.
>
> http://markorodriguez.com
>
>
> > On Mon, Aug 10, 2015 at 10:30 AM, Marko Rodriguez <ok...@gmail.com>
> > wrote:
> >
> >> Hi Stephen,
> >>
> >> First, I like the "breaking" label. Smart.
> >>
> >> Second, RELEASE.asciidoc makes more sense than the README we have as the
> >> READEME is basically a weak "getting started" (point to docs at that
> >> point), build procedure (probably just add to RELEASE.asciidoc), and
> then
> >> the release process.
> >>
> >> Thanks,
> >> Marko.
> >>
> >> http://markorodriguez.com
> >>
> >> On Aug 10, 2015, at 5:11 AM, Stephen Mallette <sp...@gmail.com>
> >> wrote:
> >>
> >>> I've merged this PR to tp30 - so we now have some guidelines on
> >>> "contributing" which covers branches/release notes.  Thanks, matt, for
> >>> getting the initial write up on that done.  I've made some minor
> >>> modifications and included info on the "breaking" label for jira and
> some
> >>> other bits.  I also move the "Issue Tracker Conventions" out of the
> >> README
> >>> and over to CONTRIBUTING - seemed to make some more sense there.  Note
> >> the
> >>> addition of the "breaking" label there. Please have a read:
> >>>
> >>>
> >>
> https://github.com/apache/incubator-tinkerpop/blob/tp30/CONTRIBUTING.asciidoc
> >>>
> >>> Note that I also adjusted the README regarding the "release process" in
> >>> relation to "release note creation":
> >>>
> >>>
> >>
> https://github.com/apache/incubator-tinkerpop/commit/c4c44ebb6e01f7178de16fb83f6d2fbe8d3590d0
> >>>
> >>> Note sure how we want to call attention to "breaking" changes in there,
> >> but
> >>> I guess we'll figure that out when the time comes.  As I look at README
> >>> now, the "release process" looks out of place - I still kinda think
> that
> >>> should just go in a new RELEASE.asciidoc file.
> >>>
> >>>
> >>> On Fri, Jul 31, 2015 at 10:52 AM, Matt Frantz <
> >> matthew.h.frantz@gmail.com>
> >>> wrote:
> >>>
> >>>> RFC here:
> >>>> https://github.com/apache/incubator-tinkerpop/pull/94
> >>>>
> >>>>
> >>>> On Fri, Jul 31, 2015 at 3:02 AM, Stephen Mallette <
> spmallette@gmail.com
> >>>
> >>>> wrote:
> >>>>
> >>>>> Hi David - agreed.  I hadn't done it yet as folks have been on
> vacation
> >>>> and
> >>>>> have not had a chance to weigh in on these ideas yet.
> >>>>>
> >>>>> On Thu, Jul 30, 2015 at 9:45 PM, David Nalley <da...@gnsa.us> wrote:
> >>>>>
> >>>>>> Guys, this thread contains awesome information - can we glean some
> of
> >>>>>> it and put it on a web page or wiki page for other new folks so they
> >>>>>> don't have to complete the question process.
> >>>>>>
> >>>>>> On Fri, Jul 24, 2015 at 9:17 AM, Stephen Mallette <
> >>>> spmallette@gmail.com>
> >>>>>> wrote:
> >>>>>>> It also just occurred to me that the 3.0.1 portion of the CHANGELOG
> >>>>> needs
> >>>>>>> to be replicated to the 3.1.0 section as the two may not be the
> same
> >>>>>>> (though should be for the most part).
> >>>>>>>
> >>>>>>> On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <
> >>>>> spmallette@gmail.com>
> >>>>>>> wrote:
> >>>>>>>
> >>>>>>>> Yup - I was playing with that.  Let's see if Marko has any
> thoughts
> >>>> on
> >>>>>> the
> >>>>>>>> matter.
> >>>>>>>>
> >>>>>>>> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <
> >>>>>> matthew.h.frantz@gmail.com>
> >>>>>>>> wrote:
> >>>>>>>>
> >>>>>>>>> JIRA has a configurable "Release Notes" report.
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>
> >>>>>
> >>>>
> >>
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
> >>>>>>>>>
> >>>>>>>>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <
> >>>>>> spmallette@gmail.com>
> >>>>>>>>> wrote:
> >>>>>>>>>
> >>>>>>>>>> I think i like that idea.  It would also force JIRA titles to be
> >>>>>> written
> >>>>>>>>>> better though so as to fit the flow of CHANGELOG....sometimes
> >>>> those
> >>>>>> are
> >>>>>>>>>> kinda slack.
> >>>>>>>>>>
> >>>>>>>>>> On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
> >>>>>>>>> matthew.h.frantz@gmail.com>
> >>>>>>>>>> wrote:
> >>>>>>>>>>
> >>>>>>>>>>> Correct.  We would make manual additions to the CHANGELOG only
> >>>> to
> >>>>>>>>> augment
> >>>>>>>>>>> the JIRA report in some way, either to explain non-JIRA
> >>>>> activities
> >>>>>> or
> >>>>>>>>> to
> >>>>>>>>>>> draw attention to particular JIRA issues that are significant
> >>>>> (and
> >>>>>> we
> >>>>>>>>>> would
> >>>>>>>>>>> cite the JIRA ticket from the CHANGELOG for those).  The
> >>>>>> definition of
> >>>>>>>>>>> "significant" is discretionary.
> >>>>>>>>>>>
> >>>>>>>>>>> On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
> >>>>>>>>> spmallette@gmail.com
> >>>>>>>>>>>
> >>>>>>>>>>> wrote:
> >>>>>>>>>>>
> >>>>>>>>>>>> Are you suggesting that on release we rectify the JIRA report
> >>>>>> with
> >>>>>>>>> the
> >>>>>>>>>>>> CHANGELOG?  In that way, if something was done by way of JIRA
> >>>>> we
> >>>>>>>>>> wouldn't
> >>>>>>>>>>>> have to enter a CHANGELOG entry manually, because on release
> >>>>> we'd
> >>>>>>>>> pick
> >>>>>>>>>> it
> >>>>>>>>>>>> up via the JIRA report?
> >>>>>>>>>>>>
> >>>>>>>>>>>> On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
> >>>>>>>>>> matthew.h.frantz@gmail.com
> >>>>>>>>>>>>
> >>>>>>>>>>>> wrote:
> >>>>>>>>>>>>
> >>>>>>>>>>>>> Perhaps in the release process we could generate a JIRA
> >>>>> report
> >>>>>> of
> >>>>>>>>>>> issues
> >>>>>>>>>>>>> marked as fixed in the specific version, and reserve the
> >>>>>> CHANGELOG
> >>>>>>>>>> for
> >>>>>>>>>>>>> significant changes and things that were not tracked
> >>>> through
> >>>>>> JIRA.
> >>>>>>>>>>>>>
> >>>>>>>>>>>>> On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
> >>>>>>>>>>> spmallette@gmail.com>
> >>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>
> >>>>>>>>>>>>>> We have typically treated CHANGELOG rather
> >>>>> unscientifically.
> >>>>>>>>> Make
> >>>>>>>>>> a
> >>>>>>>>>>>>> change
> >>>>>>>>>>>>>> of significance, then update the changelog for the
> >>>>>> appropriate
> >>>>>>>>>>> version.
> >>>>>>>>>>>>> I
> >>>>>>>>>>>>>> bat around the idea of including the issue ids all the
> >>>> time
> >>>>>> but
> >>>>>>>>>>> haven't
> >>>>>>>>>>>>>> wanted to start the trend of doing that.  Perhaps we do
> >>>>> that
> >>>>>> and
> >>>>>>>>>> make
> >>>>>>>>>>>> it
> >>>>>>>>>>>>>> optional?? Not sure how others feel on that matter.
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> >>>>>>>>>>>>> matthew.h.frantz@gmail.com>
> >>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> I just merged my fix for TINKERPOP3-782 to both tp30
> >>>> and
> >>>>>>>>>> master.  I
> >>>>>>>>>>>>>> didn't
> >>>>>>>>>>>>>>> touch CHANGELOG.  Do we do that for every bug fix?  I
> >>>>> don't
> >>>>>>>>> see
> >>>>>>>>>>>>>> references
> >>>>>>>>>>>>>>> to JIRA artifacts in the CHANGELOG.
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> >>>>>>>>>>>>> spmallette@gmail.com>
> >>>>>>>>>
> >>>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> Hi Matt,
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> I have a PR currently targeted at tp30 (because it
> >>>> is a
> >>>>>>>>>> low-risk
> >>>>>>>>>>>> bug
> >>>>>>>>>>>>>>> fix).
> >>>>>>>>>>>>>>>>> I know that we don't necessarily code review
> >>>>> everything
> >>>>>>>>> that
> >>>>>>>>>>> goes
> >>>>>>>>>>>>> in,
> >>>>>>>>>>>>>>> but
> >>>>>>>>>>>>>>>>> since I'm relatively new, I wouldn't mind someone
> >>>>>> taking a
> >>>>>>>>>> peek
> >>>>>>>>>>>> at
> >>>>>>>>>>>>>> it,
> >>>>>>>>>>>>>>>> and
> >>>>>>>>>>>>>>>>> the verify that tp30 is the best target.
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> Right - no official code review.  We pretty much tend
> >>>>> to
> >>>>>>>>> handle
> >>>>>>>>>>> it
> >>>>>>>>>>>> as
> >>>>>>>>>>>>>> you
> >>>>>>>>>>>>>>>> just did - on a case-by-case basis.
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> (I don't have permissions on the GitHub mirror for
> >>>>>>>>>>>>>>> incubating-tinkerpop.
> >>>>>>>>>>>>>>>>> Should I?)
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> I don't think you should - I don't have permissions
> >>>>>> either.
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> Also, after it is merged to tp30, is the process
> >>>>> going
> >>>>>> to
> >>>>>>>>> be
> >>>>>>>>>>>> that I
> >>>>>>>>>>>>>>> would
> >>>>>>>>>>>>>>>>> also need to merge tp30 into master?  Or do we plan
> >>>>> to
> >>>>>>>>> merge
> >>>>>>>>>>> only
> >>>>>>>>>>>>>>>>> occasionally?
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> I've been the only person committing things to tp30
> >>>> of
> >>>>>> any
> >>>>>>>>>>>> substance
> >>>>>>>>>>>>> so
> >>>>>>>>>>>>>>>> I've been doing it periodically, but generally
> >>>>> speaking,
> >>>>>> I'd
> >>>>>>>>>> say
> >>>>>>>>>>>> that
> >>>>>>>>>>>>>>> it's
> >>>>>>>>>>>>>>>> best if the person who commits to tp30 merges to
> >>>> master
> >>>>>>>>> (unless
> >>>>>>>>>>>> it's
> >>>>>>>>>>>>>>>> something pretty trivial).  In that way the person
> >>>> who
> >>>>>>>>>> committed
> >>>>>>>>>>> to
> >>>>>>>>>>>>>> tp30
> >>>>>>>>>>>>>>> is
> >>>>>>>>>>>>>>>> responsible for ensuring proper integration with
> >>>>> master.
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> >>>>>>>>>>>>>>> matthew.h.frantz@gmail.com>
> >>>>>>>>>
> >>>>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> I have a PR currently targeted at tp30 (because it
> >>>>> is a
> >>>>>>>>>>> low-risk
> >>>>>>>>>>>>> bug
> >>>>>>>>>>>>>>>> fix).
> >>>>>>>>>>>>>>>>> I know that we don't necessarily code review
> >>>>> everything
> >>>>>>>>> that
> >>>>>>>>>>> goes
> >>>>>>>>>>>>> in,
> >>>>>>>>>>>>>>> but
> >>>>>>>>>>>>>>>>> since I'm relatively new, I wouldn't mind someone
> >>>>>> taking a
> >>>>>>>>>> peek
> >>>>>>>>>>>> at
> >>>>>>>>>>>>>> it,
> >>>>>>>>>>>>>>>> and
> >>>>>>>>>>>>>>>>> the verify that tp30 is the best target.
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> (I don't have permissions on the GitHub mirror for
> >>>>>>>>>>>>>>> incubating-tinkerpop.
> >>>>>>>>>>>>>>>>> Should I?)
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> Also, after it is merged to tp30, is the process
> >>>>> going
> >>>>>> to
> >>>>>>>>> be
> >>>>>>>>>>>> that I
> >>>>>>>>>>>>>>> would
> >>>>>>>>>>>>>>>>> also need to merge tp30 into master?  Or do we plan
> >>>>> to
> >>>>>>>>> merge
> >>>>>>>>>>> only
> >>>>>>>>>>>>>>>>> occasionally?
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> >>>>>>>>>>>>>>> spmallette@gmail.com>
> >>>>>>>>>
> >>>>>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>> Thanks JB - i'm familiar with semver and I think
> >>>>> the
> >>>>>>>>> idea
> >>>>>>>>>> is
> >>>>>>>>>>> to
> >>>>>>>>>>>>>>> follow
> >>>>>>>>>>>>>>>> it
> >>>>>>>>>>>>>>>>>> in principle, in that we will save API breaking
> >>>>>> change
> >>>>>>>>> for
> >>>>>>>>>>> the
> >>>>>>>>>>>>>>> "minor"
> >>>>>>>>>>>>>>>>>> version.   imo, we should stick to the three
> >>>> digit
> >>>>>>>>> system
> >>>>>>>>>> for
> >>>>>>>>>>>> now
> >>>>>>>>>>>>>>> but I
> >>>>>>>>>>>>>>>>>> guess it's worth considering what a "breaking
> >>>>> change"
> >>>>>>>>> is in
> >>>>>>>>>>> our
> >>>>>>>>>>>>>>>> context.
> >>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>> TinkerPop is "big" - it has both public and
> >>>>> internal
> >>>>>>>>> APIs.
> >>>>>>>>>>> if
> >>>>>>>>>>>> i
> >>>>>>>>>>>>>>> change
> >>>>>>>>>>>>>>>>> the
> >>>>>>>>>>>>>>>>>> package name of an internal API in a patch
> >>>>> release, I
> >>>>>>>>>>> wouldn't
> >>>>>>>>>>>>>> expect
> >>>>>>>>>>>>>>>>> that
> >>>>>>>>>>>>>>>>>> to break anyone and thus I'm not sure I'd
> >>>> consider
> >>>>>> that
> >>>>>>>>> a
> >>>>>>>>>>>>> breaking
> >>>>>>>>>>>>>>>> change
> >>>>>>>>>>>>>>>>>> (though it's always interesting to see how folks
> >>>>>> find
> >>>>>>>>>> their
> >>>>>>>>>>>> way
> >>>>>>>>>>>>>> into
> >>>>>>>>>>>>>>>>> using
> >>>>>>>>>>>>>>>>>> our internal classes) .  To me the "breaking
> >>>>> changes"
> >>>>>>>>> are
> >>>>>>>>>>> ones
> >>>>>>>>>>>>> that
> >>>>>>>>>>>>>>>> occur
> >>>>>>>>>>>>>>>>>> in the public classes (i.e. the ones people are
> >>>>>> likely
> >>>>>>>>> to
> >>>>>>>>>>> use)
> >>>>>>>>>>>>>> like:
> >>>>>>>>>>>>>>>>>> gremlin driver classes, structure API for
> >>>> vendors,
> >>>>>> step
> >>>>>>>>>>> classes
> >>>>>>>>>>>>> and
> >>>>>>>>>>>>>>>>>> GraphTraversal/GraphTraversalSource, etc.
> >>>> Changing
> >>>>>> those
> >>>>>>>>>>>> classes
> >>>>>>>>>>>>> in
> >>>>>>>>>>>>>>>> some
> >>>>>>>>>>>>>>>>>> way, would break the greatest percentage of
> >>>> users.
> >>>>>> I'm
> >>>>>>>>> not
> >>>>>>>>>>>> sure
> >>>>>>>>>>>>>> how
> >>>>>>>>>>>>>>>>> others
> >>>>>>>>>>>>>>>>>> feel, but I tend to think of "breaking change" in
> >>>>>> that
> >>>>>>>>> more
> >>>>>>>>>>>> fuzzy
> >>>>>>>>>>>>>>>>> fashion.
> >>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>> On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste
> >>>>> Musso
> >>>>>> <
> >>>>>>>>>>>>>>>> jbmusso@gmail.com>
> >>>>>>>>>
> >>>>>>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>> Related - have you considered using semantic
> >>>>>>>>> versioning
> >>>>>>>>>> [1]
> >>>>>>>>>>>>>>>>>>> (major.minor.patch)? Roughly, semver states
> >>>> that
> >>>>>>>>> breaking
> >>>>>>>>>>>>> changes
> >>>>>>>>>>>>>>>>>>> should bump major, new backward-compatible
> >>>>> features
> >>>>>>>>>> should
> >>>>>>>>>>>> bump
> >>>>>>>>>>>>>>> minor
> >>>>>>>>>>>>>>>>>>> while bug fixes should bump patch. It also
> >>>>> supports
> >>>>>>>>>>>> pre-release
> >>>>>>>>>>>>>>>>>>> version (-alpha, -incubating or -whatever
> >>>>>> suffixes).
> >>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>> In order to avoid having the first digit
> >>>> (major)
> >>>>>> being
> >>>>>>>>>>> bumped
> >>>>>>>>>>>>> too
> >>>>>>>>>>>>>>>>>>> often (TP3 shall remain TP3!), a variation
> >>>> could
> >>>>>> be:
> >>>>>>>>>>>>>>>>>>> marketing.major.minor.patch (downside to that
> >>>> is
> >>>>> 4
> >>>>>>>>> digits
> >>>>>>>>>>>>>>> versioning
> >>>>>>>>>>>>>>>>>>> instead of 3). For example, adding a new
> >>>> Gremlin
> >>>>>> step
> >>>>>>>>>> would
> >>>>>>>>>>>>> bump
> >>>>>>>>>>>>>>>> minor
> >>>>>>>>>>>>>>>>>>> while changing a step signature in a
> >>>>>>>>>> backward-incompatible
> >>>>>>>>>>>>> manner
> >>>>>>>>>>>>>>>>>>> would bump major.
> >>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>> semver is very popular in the
> >>>> JavaScript/Node.js
> >>>>>> world
> >>>>>>>>>> and
> >>>>>>>>>>>> used
> >>>>>>>>>>>>>>>>>>> extensively with npm (node package manager).
> >>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>> Just some thoughts.
> >>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>> Jean-Baptiste
> >>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>> [1] http://semver.org/
> >>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>> On Mon, Jul 13, 2015 at 1:20 PM, Stephen
> >>>>> Mallette <
> >>>>>>>>>>>>>>>>> spmallette@gmail.com>
> >>>>>>>>>
> >>>>>>>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>>>>>>> I think it's worthwhile for us to do
> >>>> something
> >>>>>> we've
> >>>>>>>>>> not
> >>>>>>>>>>>>> really
> >>>>>>>>>>>>>>>> done
> >>>>>>>>>>>>>>>>>>> before
> >>>>>>>>>>>>>>>>>>>> with any of the TinkerPop projects: use
> >>>>>> branches. We
> >>>>>>>>>>>>> typically
> >>>>>>>>>>>>>>> tend
> >>>>>>>>>>>>>>>>> to
> >>>>>>>>>>>>>>>>>>> use
> >>>>>>>>>>>>>>>>>>>> branches for major refactoring that we might
> >>>>>> throw
> >>>>>>>>> out,
> >>>>>>>>>>> but
> >>>>>>>>>>>>> not
> >>>>>>>>>>>>>>>>> really
> >>>>>>>>>>>>>>>>>>> for
> >>>>>>>>>>>>>>>>>>>> release management. As we look past release
> >>>>>> 3.0.0, I
> >>>>>>>>>>> think
> >>>>>>>>>>>> we
> >>>>>>>>>>>>>>> will
> >>>>>>>>>>>>>>>>> want
> >>>>>>>>>>>>>>>>>>> to
> >>>>>>>>>>>>>>>>>>>> have the capability to do more frequent minor
> >>>>>>>>> releases
> >>>>>>>>>>>> (e.g.
> >>>>>>>>>>>>>>> 3.0.1,
> >>>>>>>>>>>>>>>>>>> 3.0.2,
> >>>>>>>>>>>>>>>>>>>> etc) while still being able to do work for a
> >>>>>> future
> >>>>>>>>>> 3.1.x
> >>>>>>>>>>>>> line
> >>>>>>>>>>>>>> of
> >>>>>>>>>>>>>>>>> code.
> >>>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>>> I think we can do this without too much
> >>>> change
> >>>>>> if we
> >>>>>>>>>>>>> introduce
> >>>>>>>>>>>>>> a
> >>>>>>>>>>>>>>>>> simple
> >>>>>>>>>>>>>>>>>>>> branch system.  Release branch rules would be
> >>>>>>>>> simple -
> >>>>>>>>>> we
> >>>>>>>>>>>>>> create
> >>>>>>>>>>>>>>> a
> >>>>>>>>>>>>>>>>> new
> >>>>>>>>>>>>>>>>>>>> branch from master called tp31 for the 3.1.x
> >>>>>> line of
> >>>>>>>>>>> code.
> >>>>>>>>>>>>> Any
> >>>>>>>>>>>>>>>>> changes
> >>>>>>>>>>>>>>>>>>>> that are "breaking", introduce significant
> >>>>> risk,
> >>>>>> a
> >>>>>>>>>>> "major"
> >>>>>>>>>>>>>>> feature,
> >>>>>>>>>>>>>>>>>> etc.
> >>>>>>>>>>>>>>>>>>>> would be committed there.  All other changes,
> >>>>> bug
> >>>>>>>>>> fixes,
> >>>>>>>>>>>>>>>> non-breaking
> >>>>>>>>>>>>>>>>>>>> refactoring of major APIs, "minor" features,
> >>>>> etc.
> >>>>>>>>> would
> >>>>>>>>>>>>> simply
> >>>>>>>>>>>>>>>> commit
> >>>>>>>>>>>>>>>>>> to
> >>>>>>>>>>>>>>>>>>>> master.  the master branch effectively
> >>>> becomes
> >>>>>> the
> >>>>>>>>>> 3.0.x
> >>>>>>>>>>>> line
> >>>>>>>>>>>>>> of
> >>>>>>>>>>>>>>>>> code.
> >>>>>>>>>>>>>>>>>>>> Under this approach the merge process is
> >>>> pretty
> >>>>>>>>> simple
> >>>>>>>>>> in
> >>>>>>>>>>>>> that
> >>>>>>>>>>>>>> we
> >>>>>>>>>>>>>>>>> just
> >>>>>>>>>>>>>>>>>>>> merge forward (i.e. master merges to to
> >>>> tp31).
> >>>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>>> When the day comes that we're ready to
> >>>> release
> >>>>>>>>> 3.1.0,
> >>>>>>>>>> we
> >>>>>>>>>>>>> merge
> >>>>>>>>>>>>>>> tp31
> >>>>>>>>>>>>>>>>>> back
> >>>>>>>>>>>>>>>>>>> to
> >>>>>>>>>>>>>>>>>>>> master and create tp32 and use the same model
> >>>>>> where
> >>>>>>>>> the
> >>>>>>>>>>>> 3.1.x
> >>>>>>>>>>>>>>> line
> >>>>>>>>>>>>>>>> is
> >>>>>>>>>>>>>>>>>>>> master and the 3.2.x line is tp32.  Of
> >>>> course,
> >>>>>> under
> >>>>>>>>>> this
> >>>>>>>>>>>>> model
> >>>>>>>>>>>>>>> we
> >>>>>>>>>>>>>>>>> are
> >>>>>>>>>>>>>>>>>>>> really supporting just the previous minor
> >>>>>> version,
> >>>>>>>>>> which
> >>>>>>>>>>>> for
> >>>>>>>>>>>>>>> right
> >>>>>>>>>>>>>>>>> now
> >>>>>>>>>>>>>>>>>>>> seems acceptable to me.  That's more than
> >>>> what
> >>>>>> we've
> >>>>>>>>>> ever
> >>>>>>>>>>>>>> really
> >>>>>>>>>>>>>>>> done
> >>>>>>>>>>>>>>>>>>> well,
> >>>>>>>>>>>>>>>>>>>> so that feels like a good starting point in
> >>>> my
> >>>>>> book.
> >>>>>>>>>>> After
> >>>>>>>>>>>>> we
> >>>>>>>>>>>>>>>>> release
> >>>>>>>>>>>>>>>>>>>> 3.1.0 we can revisit and decide if a more
> >>>>> complex
> >>>>>>>>>>> branching
> >>>>>>>>>>>>>>>> strategy
> >>>>>>>>>>>>>>>>> is
> >>>>>>>>>>>>>>>>>>>> needed.
> >>>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>
> >>>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>
> >>>>>
> >>>>
> >>
> >>
>
>

Re: branching after GA

[Marko Rodriguez <ok...@gmail.com>]

> maybe we fix up the README to be a bit more user focused and do a little
> better with project description and "getting started" as part of this
> change.  i kinda feel like CONTRIBUTING is a better place for the deep
> details of the build commands/options plus intellij setup...thoughts on
> that?

I concur.

Marko.

http://markorodriguez.com


> On Mon, Aug 10, 2015 at 10:30 AM, Marko Rodriguez <ok...@gmail.com>
> wrote:
> 
>> Hi Stephen,
>> 
>> First, I like the "breaking" label. Smart.
>> 
>> Second, RELEASE.asciidoc makes more sense than the README we have as the
>> READEME is basically a weak "getting started" (point to docs at that
>> point), build procedure (probably just add to RELEASE.asciidoc), and then
>> the release process.
>> 
>> Thanks,
>> Marko.
>> 
>> http://markorodriguez.com
>> 
>> On Aug 10, 2015, at 5:11 AM, Stephen Mallette <sp...@gmail.com>
>> wrote:
>> 
>>> I've merged this PR to tp30 - so we now have some guidelines on
>>> "contributing" which covers branches/release notes.  Thanks, matt, for
>>> getting the initial write up on that done.  I've made some minor
>>> modifications and included info on the "breaking" label for jira and some
>>> other bits.  I also move the "Issue Tracker Conventions" out of the
>> README
>>> and over to CONTRIBUTING - seemed to make some more sense there.  Note
>> the
>>> addition of the "breaking" label there. Please have a read:
>>> 
>>> 
>> https://github.com/apache/incubator-tinkerpop/blob/tp30/CONTRIBUTING.asciidoc
>>> 
>>> Note that I also adjusted the README regarding the "release process" in
>>> relation to "release note creation":
>>> 
>>> 
>> https://github.com/apache/incubator-tinkerpop/commit/c4c44ebb6e01f7178de16fb83f6d2fbe8d3590d0
>>> 
>>> Note sure how we want to call attention to "breaking" changes in there,
>> but
>>> I guess we'll figure that out when the time comes.  As I look at README
>>> now, the "release process" looks out of place - I still kinda think that
>>> should just go in a new RELEASE.asciidoc file.
>>> 
>>> 
>>> On Fri, Jul 31, 2015 at 10:52 AM, Matt Frantz <
>> matthew.h.frantz@gmail.com>
>>> wrote:
>>> 
>>>> RFC here:
>>>> https://github.com/apache/incubator-tinkerpop/pull/94
>>>> 
>>>> 
>>>> On Fri, Jul 31, 2015 at 3:02 AM, Stephen Mallette <spmallette@gmail.com
>>> 
>>>> wrote:
>>>> 
>>>>> Hi David - agreed.  I hadn't done it yet as folks have been on vacation
>>>> and
>>>>> have not had a chance to weigh in on these ideas yet.
>>>>> 
>>>>> On Thu, Jul 30, 2015 at 9:45 PM, David Nalley <da...@gnsa.us> wrote:
>>>>> 
>>>>>> Guys, this thread contains awesome information - can we glean some of
>>>>>> it and put it on a web page or wiki page for other new folks so they
>>>>>> don't have to complete the question process.
>>>>>> 
>>>>>> On Fri, Jul 24, 2015 at 9:17 AM, Stephen Mallette <
>>>> spmallette@gmail.com>
>>>>>> wrote:
>>>>>>> It also just occurred to me that the 3.0.1 portion of the CHANGELOG
>>>>> needs
>>>>>>> to be replicated to the 3.1.0 section as the two may not be the same
>>>>>>> (though should be for the most part).
>>>>>>> 
>>>>>>> On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <
>>>>> spmallette@gmail.com>
>>>>>>> wrote:
>>>>>>> 
>>>>>>>> Yup - I was playing with that.  Let's see if Marko has any thoughts
>>>> on
>>>>>> the
>>>>>>>> matter.
>>>>>>>> 
>>>>>>>> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <
>>>>>> matthew.h.frantz@gmail.com>
>>>>>>>> wrote:
>>>>>>>> 
>>>>>>>>> JIRA has a configurable "Release Notes" report.
>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> 
>>>>>> 
>>>>> 
>>>> 
>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
>>>>>>>>> 
>>>>>>>>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <
>>>>>> spmallette@gmail.com>
>>>>>>>>> wrote:
>>>>>>>>> 
>>>>>>>>>> I think i like that idea.  It would also force JIRA titles to be
>>>>>> written
>>>>>>>>>> better though so as to fit the flow of CHANGELOG....sometimes
>>>> those
>>>>>> are
>>>>>>>>>> kinda slack.
>>>>>>>>>> 
>>>>>>>>>> On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
>>>>>>>>> matthew.h.frantz@gmail.com>
>>>>>>>>>> wrote:
>>>>>>>>>> 
>>>>>>>>>>> Correct.  We would make manual additions to the CHANGELOG only
>>>> to
>>>>>>>>> augment
>>>>>>>>>>> the JIRA report in some way, either to explain non-JIRA
>>>>> activities
>>>>>> or
>>>>>>>>> to
>>>>>>>>>>> draw attention to particular JIRA issues that are significant
>>>>> (and
>>>>>> we
>>>>>>>>>> would
>>>>>>>>>>> cite the JIRA ticket from the CHANGELOG for those).  The
>>>>>> definition of
>>>>>>>>>>> "significant" is discretionary.
>>>>>>>>>>> 
>>>>>>>>>>> On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
>>>>>>>>> spmallette@gmail.com
>>>>>>>>>>> 
>>>>>>>>>>> wrote:
>>>>>>>>>>> 
>>>>>>>>>>>> Are you suggesting that on release we rectify the JIRA report
>>>>>> with
>>>>>>>>> the
>>>>>>>>>>>> CHANGELOG?  In that way, if something was done by way of JIRA
>>>>> we
>>>>>>>>>> wouldn't
>>>>>>>>>>>> have to enter a CHANGELOG entry manually, because on release
>>>>> we'd
>>>>>>>>> pick
>>>>>>>>>> it
>>>>>>>>>>>> up via the JIRA report?
>>>>>>>>>>>> 
>>>>>>>>>>>> On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
>>>>>>>>>> matthew.h.frantz@gmail.com
>>>>>>>>>>>> 
>>>>>>>>>>>> wrote:
>>>>>>>>>>>> 
>>>>>>>>>>>>> Perhaps in the release process we could generate a JIRA
>>>>> report
>>>>>> of
>>>>>>>>>>> issues
>>>>>>>>>>>>> marked as fixed in the specific version, and reserve the
>>>>>> CHANGELOG
>>>>>>>>>> for
>>>>>>>>>>>>> significant changes and things that were not tracked
>>>> through
>>>>>> JIRA.
>>>>>>>>>>>>> 
>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
>>>>>>>>>>> spmallette@gmail.com>
>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>> 
>>>>>>>>>>>>>> We have typically treated CHANGELOG rather
>>>>> unscientifically.
>>>>>>>>> Make
>>>>>>>>>> a
>>>>>>>>>>>>> change
>>>>>>>>>>>>>> of significance, then update the changelog for the
>>>>>> appropriate
>>>>>>>>>>> version.
>>>>>>>>>>>>> I
>>>>>>>>>>>>>> bat around the idea of including the issue ids all the
>>>> time
>>>>>> but
>>>>>>>>>>> haven't
>>>>>>>>>>>>>> wanted to start the trend of doing that.  Perhaps we do
>>>>> that
>>>>>> and
>>>>>>>>>> make
>>>>>>>>>>>> it
>>>>>>>>>>>>>> optional?? Not sure how others feel on that matter.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
>>>>>>>>>>>>> matthew.h.frantz@gmail.com>
>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> I just merged my fix for TINKERPOP3-782 to both tp30
>>>> and
>>>>>>>>>> master.  I
>>>>>>>>>>>>>> didn't
>>>>>>>>>>>>>>> touch CHANGELOG.  Do we do that for every bug fix?  I
>>>>> don't
>>>>>>>>> see
>>>>>>>>>>>>>> references
>>>>>>>>>>>>>>> to JIRA artifacts in the CHANGELOG.
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
>>>>>>>>>>>>> spmallette@gmail.com>
>>>>>>>>> 
>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> Hi Matt,
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> I have a PR currently targeted at tp30 (because it
>>>> is a
>>>>>>>>>> low-risk
>>>>>>>>>>>> bug
>>>>>>>>>>>>>>> fix).
>>>>>>>>>>>>>>>>> I know that we don't necessarily code review
>>>>> everything
>>>>>>>>> that
>>>>>>>>>>> goes
>>>>>>>>>>>>> in,
>>>>>>>>>>>>>>> but
>>>>>>>>>>>>>>>>> since I'm relatively new, I wouldn't mind someone
>>>>>> taking a
>>>>>>>>>> peek
>>>>>>>>>>>> at
>>>>>>>>>>>>>> it,
>>>>>>>>>>>>>>>> and
>>>>>>>>>>>>>>>>> the verify that tp30 is the best target.
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> Right - no official code review.  We pretty much tend
>>>>> to
>>>>>>>>> handle
>>>>>>>>>>> it
>>>>>>>>>>>> as
>>>>>>>>>>>>>> you
>>>>>>>>>>>>>>>> just did - on a case-by-case basis.
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> (I don't have permissions on the GitHub mirror for
>>>>>>>>>>>>>>> incubating-tinkerpop.
>>>>>>>>>>>>>>>>> Should I?)
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> I don't think you should - I don't have permissions
>>>>>> either.
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> Also, after it is merged to tp30, is the process
>>>>> going
>>>>>> to
>>>>>>>>> be
>>>>>>>>>>>> that I
>>>>>>>>>>>>>>> would
>>>>>>>>>>>>>>>>> also need to merge tp30 into master?  Or do we plan
>>>>> to
>>>>>>>>> merge
>>>>>>>>>>> only
>>>>>>>>>>>>>>>>> occasionally?
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> I've been the only person committing things to tp30
>>>> of
>>>>>> any
>>>>>>>>>>>> substance
>>>>>>>>>>>>> so
>>>>>>>>>>>>>>>> I've been doing it periodically, but generally
>>>>> speaking,
>>>>>> I'd
>>>>>>>>>> say
>>>>>>>>>>>> that
>>>>>>>>>>>>>>> it's
>>>>>>>>>>>>>>>> best if the person who commits to tp30 merges to
>>>> master
>>>>>>>>> (unless
>>>>>>>>>>>> it's
>>>>>>>>>>>>>>>> something pretty trivial).  In that way the person
>>>> who
>>>>>>>>>> committed
>>>>>>>>>>> to
>>>>>>>>>>>>>> tp30
>>>>>>>>>>>>>>> is
>>>>>>>>>>>>>>>> responsible for ensuring proper integration with
>>>>> master.
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
>>>>>>>>>>>>>>> matthew.h.frantz@gmail.com>
>>>>>>>>> 
>>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> I have a PR currently targeted at tp30 (because it
>>>>> is a
>>>>>>>>>>> low-risk
>>>>>>>>>>>>> bug
>>>>>>>>>>>>>>>> fix).
>>>>>>>>>>>>>>>>> I know that we don't necessarily code review
>>>>> everything
>>>>>>>>> that
>>>>>>>>>>> goes
>>>>>>>>>>>>> in,
>>>>>>>>>>>>>>> but
>>>>>>>>>>>>>>>>> since I'm relatively new, I wouldn't mind someone
>>>>>> taking a
>>>>>>>>>> peek
>>>>>>>>>>>> at
>>>>>>>>>>>>>> it,
>>>>>>>>>>>>>>>> and
>>>>>>>>>>>>>>>>> the verify that tp30 is the best target.
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> (I don't have permissions on the GitHub mirror for
>>>>>>>>>>>>>>> incubating-tinkerpop.
>>>>>>>>>>>>>>>>> Should I?)
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> Also, after it is merged to tp30, is the process
>>>>> going
>>>>>> to
>>>>>>>>> be
>>>>>>>>>>>> that I
>>>>>>>>>>>>>>> would
>>>>>>>>>>>>>>>>> also need to merge tp30 into master?  Or do we plan
>>>>> to
>>>>>>>>> merge
>>>>>>>>>>> only
>>>>>>>>>>>>>>>>> occasionally?
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
>>>>>>>>>>>>>>> spmallette@gmail.com>
>>>>>>>>> 
>>>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>> Thanks JB - i'm familiar with semver and I think
>>>>> the
>>>>>>>>> idea
>>>>>>>>>> is
>>>>>>>>>>> to
>>>>>>>>>>>>>>> follow
>>>>>>>>>>>>>>>> it
>>>>>>>>>>>>>>>>>> in principle, in that we will save API breaking
>>>>>> change
>>>>>>>>> for
>>>>>>>>>>> the
>>>>>>>>>>>>>>> "minor"
>>>>>>>>>>>>>>>>>> version.   imo, we should stick to the three
>>>> digit
>>>>>>>>> system
>>>>>>>>>> for
>>>>>>>>>>>> now
>>>>>>>>>>>>>>> but I
>>>>>>>>>>>>>>>>>> guess it's worth considering what a "breaking
>>>>> change"
>>>>>>>>> is in
>>>>>>>>>>> our
>>>>>>>>>>>>>>>> context.
>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>> TinkerPop is "big" - it has both public and
>>>>> internal
>>>>>>>>> APIs.
>>>>>>>>>>> if
>>>>>>>>>>>> i
>>>>>>>>>>>>>>> change
>>>>>>>>>>>>>>>>> the
>>>>>>>>>>>>>>>>>> package name of an internal API in a patch
>>>>> release, I
>>>>>>>>>>> wouldn't
>>>>>>>>>>>>>> expect
>>>>>>>>>>>>>>>>> that
>>>>>>>>>>>>>>>>>> to break anyone and thus I'm not sure I'd
>>>> consider
>>>>>> that
>>>>>>>>> a
>>>>>>>>>>>>> breaking
>>>>>>>>>>>>>>>> change
>>>>>>>>>>>>>>>>>> (though it's always interesting to see how folks
>>>>>> find
>>>>>>>>>> their
>>>>>>>>>>>> way
>>>>>>>>>>>>>> into
>>>>>>>>>>>>>>>>> using
>>>>>>>>>>>>>>>>>> our internal classes) .  To me the "breaking
>>>>> changes"
>>>>>>>>> are
>>>>>>>>>>> ones
>>>>>>>>>>>>> that
>>>>>>>>>>>>>>>> occur
>>>>>>>>>>>>>>>>>> in the public classes (i.e. the ones people are
>>>>>> likely
>>>>>>>>> to
>>>>>>>>>>> use)
>>>>>>>>>>>>>> like:
>>>>>>>>>>>>>>>>>> gremlin driver classes, structure API for
>>>> vendors,
>>>>>> step
>>>>>>>>>>> classes
>>>>>>>>>>>>> and
>>>>>>>>>>>>>>>>>> GraphTraversal/GraphTraversalSource, etc.
>>>> Changing
>>>>>> those
>>>>>>>>>>>> classes
>>>>>>>>>>>>> in
>>>>>>>>>>>>>>>> some
>>>>>>>>>>>>>>>>>> way, would break the greatest percentage of
>>>> users.
>>>>>> I'm
>>>>>>>>> not
>>>>>>>>>>>> sure
>>>>>>>>>>>>>> how
>>>>>>>>>>>>>>>>> others
>>>>>>>>>>>>>>>>>> feel, but I tend to think of "breaking change" in
>>>>>> that
>>>>>>>>> more
>>>>>>>>>>>> fuzzy
>>>>>>>>>>>>>>>>> fashion.
>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>> On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste
>>>>> Musso
>>>>>> <
>>>>>>>>>>>>>>>> jbmusso@gmail.com>
>>>>>>>>> 
>>>>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>> Related - have you considered using semantic
>>>>>>>>> versioning
>>>>>>>>>> [1]
>>>>>>>>>>>>>>>>>>> (major.minor.patch)? Roughly, semver states
>>>> that
>>>>>>>>> breaking
>>>>>>>>>>>>> changes
>>>>>>>>>>>>>>>>>>> should bump major, new backward-compatible
>>>>> features
>>>>>>>>>> should
>>>>>>>>>>>> bump
>>>>>>>>>>>>>>> minor
>>>>>>>>>>>>>>>>>>> while bug fixes should bump patch. It also
>>>>> supports
>>>>>>>>>>>> pre-release
>>>>>>>>>>>>>>>>>>> version (-alpha, -incubating or -whatever
>>>>>> suffixes).
>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>> In order to avoid having the first digit
>>>> (major)
>>>>>> being
>>>>>>>>>>> bumped
>>>>>>>>>>>>> too
>>>>>>>>>>>>>>>>>>> often (TP3 shall remain TP3!), a variation
>>>> could
>>>>>> be:
>>>>>>>>>>>>>>>>>>> marketing.major.minor.patch (downside to that
>>>> is
>>>>> 4
>>>>>>>>> digits
>>>>>>>>>>>>>>> versioning
>>>>>>>>>>>>>>>>>>> instead of 3). For example, adding a new
>>>> Gremlin
>>>>>> step
>>>>>>>>>> would
>>>>>>>>>>>>> bump
>>>>>>>>>>>>>>>> minor
>>>>>>>>>>>>>>>>>>> while changing a step signature in a
>>>>>>>>>> backward-incompatible
>>>>>>>>>>>>> manner
>>>>>>>>>>>>>>>>>>> would bump major.
>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>> semver is very popular in the
>>>> JavaScript/Node.js
>>>>>> world
>>>>>>>>>> and
>>>>>>>>>>>> used
>>>>>>>>>>>>>>>>>>> extensively with npm (node package manager).
>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>> Just some thoughts.
>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>> Jean-Baptiste
>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>> [1] http://semver.org/
>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>> On Mon, Jul 13, 2015 at 1:20 PM, Stephen
>>>>> Mallette <
>>>>>>>>>>>>>>>>> spmallette@gmail.com>
>>>>>>>>> 
>>>>>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>>>>>>> I think it's worthwhile for us to do
>>>> something
>>>>>> we've
>>>>>>>>>> not
>>>>>>>>>>>>> really
>>>>>>>>>>>>>>>> done
>>>>>>>>>>>>>>>>>>> before
>>>>>>>>>>>>>>>>>>>> with any of the TinkerPop projects: use
>>>>>> branches. We
>>>>>>>>>>>>> typically
>>>>>>>>>>>>>>> tend
>>>>>>>>>>>>>>>>> to
>>>>>>>>>>>>>>>>>>> use
>>>>>>>>>>>>>>>>>>>> branches for major refactoring that we might
>>>>>> throw
>>>>>>>>> out,
>>>>>>>>>>> but
>>>>>>>>>>>>> not
>>>>>>>>>>>>>>>>> really
>>>>>>>>>>>>>>>>>>> for
>>>>>>>>>>>>>>>>>>>> release management. As we look past release
>>>>>> 3.0.0, I
>>>>>>>>>>> think
>>>>>>>>>>>> we
>>>>>>>>>>>>>>> will
>>>>>>>>>>>>>>>>> want
>>>>>>>>>>>>>>>>>>> to
>>>>>>>>>>>>>>>>>>>> have the capability to do more frequent minor
>>>>>>>>> releases
>>>>>>>>>>>> (e.g.
>>>>>>>>>>>>>>> 3.0.1,
>>>>>>>>>>>>>>>>>>> 3.0.2,
>>>>>>>>>>>>>>>>>>>> etc) while still being able to do work for a
>>>>>> future
>>>>>>>>>> 3.1.x
>>>>>>>>>>>>> line
>>>>>>>>>>>>>> of
>>>>>>>>>>>>>>>>> code.
>>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>>> I think we can do this without too much
>>>> change
>>>>>> if we
>>>>>>>>>>>>> introduce
>>>>>>>>>>>>>> a
>>>>>>>>>>>>>>>>> simple
>>>>>>>>>>>>>>>>>>>> branch system.  Release branch rules would be
>>>>>>>>> simple -
>>>>>>>>>> we
>>>>>>>>>>>>>> create
>>>>>>>>>>>>>>> a
>>>>>>>>>>>>>>>>> new
>>>>>>>>>>>>>>>>>>>> branch from master called tp31 for the 3.1.x
>>>>>> line of
>>>>>>>>>>> code.
>>>>>>>>>>>>> Any
>>>>>>>>>>>>>>>>> changes
>>>>>>>>>>>>>>>>>>>> that are "breaking", introduce significant
>>>>> risk,
>>>>>> a
>>>>>>>>>>> "major"
>>>>>>>>>>>>>>> feature,
>>>>>>>>>>>>>>>>>> etc.
>>>>>>>>>>>>>>>>>>>> would be committed there.  All other changes,
>>>>> bug
>>>>>>>>>> fixes,
>>>>>>>>>>>>>>>> non-breaking
>>>>>>>>>>>>>>>>>>>> refactoring of major APIs, "minor" features,
>>>>> etc.
>>>>>>>>> would
>>>>>>>>>>>>> simply
>>>>>>>>>>>>>>>> commit
>>>>>>>>>>>>>>>>>> to
>>>>>>>>>>>>>>>>>>>> master.  the master branch effectively
>>>> becomes
>>>>>> the
>>>>>>>>>> 3.0.x
>>>>>>>>>>>> line
>>>>>>>>>>>>>> of
>>>>>>>>>>>>>>>>> code.
>>>>>>>>>>>>>>>>>>>> Under this approach the merge process is
>>>> pretty
>>>>>>>>> simple
>>>>>>>>>> in
>>>>>>>>>>>>> that
>>>>>>>>>>>>>> we
>>>>>>>>>>>>>>>>> just
>>>>>>>>>>>>>>>>>>>> merge forward (i.e. master merges to to
>>>> tp31).
>>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>>>> When the day comes that we're ready to
>>>> release
>>>>>>>>> 3.1.0,
>>>>>>>>>> we
>>>>>>>>>>>>> merge
>>>>>>>>>>>>>>> tp31
>>>>>>>>>>>>>>>>>> back
>>>>>>>>>>>>>>>>>>> to
>>>>>>>>>>>>>>>>>>>> master and create tp32 and use the same model
>>>>>> where
>>>>>>>>> the
>>>>>>>>>>>> 3.1.x
>>>>>>>>>>>>>>> line
>>>>>>>>>>>>>>>> is
>>>>>>>>>>>>>>>>>>>> master and the 3.2.x line is tp32.  Of
>>>> course,
>>>>>> under
>>>>>>>>>> this
>>>>>>>>>>>>> model
>>>>>>>>>>>>>>> we
>>>>>>>>>>>>>>>>> are
>>>>>>>>>>>>>>>>>>>> really supporting just the previous minor
>>>>>> version,
>>>>>>>>>> which
>>>>>>>>>>>> for
>>>>>>>>>>>>>>> right
>>>>>>>>>>>>>>>>> now
>>>>>>>>>>>>>>>>>>>> seems acceptable to me.  That's more than
>>>> what
>>>>>> we've
>>>>>>>>>> ever
>>>>>>>>>>>>>> really
>>>>>>>>>>>>>>>> done
>>>>>>>>>>>>>>>>>>> well,
>>>>>>>>>>>>>>>>>>>> so that feels like a good starting point in
>>>> my
>>>>>> book.
>>>>>>>>>>> After
>>>>>>>>>>>>> we
>>>>>>>>>>>>>>>>> release
>>>>>>>>>>>>>>>>>>>> 3.1.0 we can revisit and decide if a more
>>>>> complex
>>>>>>>>>>> branching
>>>>>>>>>>>>>>>> strategy
>>>>>>>>>>>>>>>>> is
>>>>>>>>>>>>>>>>>>>> needed.
>>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>>>> 
>> 
>> 

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

> Second, RELEASE.asciidoc makes more sense than the README


ok - i can adjust that.


> we have as the READEME is basically a weak "getting started" (point to
> docs at that point), build procedure (probably just add to
> RELEASE.asciidoc), and then the release process.
>

maybe we fix up the README to be a bit more user focused and do a little
better with project description and "getting started" as part of this
change.  i kinda feel like CONTRIBUTING is a better place for the deep
details of the build commands/options plus intellij setup...thoughts on
that?



On Mon, Aug 10, 2015 at 10:30 AM, Marko Rodriguez <ok...@gmail.com>
wrote:

> Hi Stephen,
>
> First, I like the "breaking" label. Smart.
>
> Second, RELEASE.asciidoc makes more sense than the README we have as the
> READEME is basically a weak "getting started" (point to docs at that
> point), build procedure (probably just add to RELEASE.asciidoc), and then
> the release process.
>
> Thanks,
> Marko.
>
> http://markorodriguez.com
>
> On Aug 10, 2015, at 5:11 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > I've merged this PR to tp30 - so we now have some guidelines on
> > "contributing" which covers branches/release notes.  Thanks, matt, for
> > getting the initial write up on that done.  I've made some minor
> > modifications and included info on the "breaking" label for jira and some
> > other bits.  I also move the "Issue Tracker Conventions" out of the
> README
> > and over to CONTRIBUTING - seemed to make some more sense there.  Note
> the
> > addition of the "breaking" label there. Please have a read:
> >
> >
> https://github.com/apache/incubator-tinkerpop/blob/tp30/CONTRIBUTING.asciidoc
> >
> > Note that I also adjusted the README regarding the "release process" in
> > relation to "release note creation":
> >
> >
> https://github.com/apache/incubator-tinkerpop/commit/c4c44ebb6e01f7178de16fb83f6d2fbe8d3590d0
> >
> > Note sure how we want to call attention to "breaking" changes in there,
> but
> > I guess we'll figure that out when the time comes.  As I look at README
> > now, the "release process" looks out of place - I still kinda think that
> > should just go in a new RELEASE.asciidoc file.
> >
> >
> > On Fri, Jul 31, 2015 at 10:52 AM, Matt Frantz <
> matthew.h.frantz@gmail.com>
> > wrote:
> >
> >> RFC here:
> >> https://github.com/apache/incubator-tinkerpop/pull/94
> >>
> >>
> >> On Fri, Jul 31, 2015 at 3:02 AM, Stephen Mallette <spmallette@gmail.com
> >
> >> wrote:
> >>
> >>> Hi David - agreed.  I hadn't done it yet as folks have been on vacation
> >> and
> >>> have not had a chance to weigh in on these ideas yet.
> >>>
> >>> On Thu, Jul 30, 2015 at 9:45 PM, David Nalley <da...@gnsa.us> wrote:
> >>>
> >>>> Guys, this thread contains awesome information - can we glean some of
> >>>> it and put it on a web page or wiki page for other new folks so they
> >>>> don't have to complete the question process.
> >>>>
> >>>> On Fri, Jul 24, 2015 at 9:17 AM, Stephen Mallette <
> >> spmallette@gmail.com>
> >>>> wrote:
> >>>>> It also just occurred to me that the 3.0.1 portion of the CHANGELOG
> >>> needs
> >>>>> to be replicated to the 3.1.0 section as the two may not be the same
> >>>>> (though should be for the most part).
> >>>>>
> >>>>> On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <
> >>> spmallette@gmail.com>
> >>>>> wrote:
> >>>>>
> >>>>>> Yup - I was playing with that.  Let's see if Marko has any thoughts
> >> on
> >>>> the
> >>>>>> matter.
> >>>>>>
> >>>>>> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <
> >>>> matthew.h.frantz@gmail.com>
> >>>>>> wrote:
> >>>>>>
> >>>>>>> JIRA has a configurable "Release Notes" report.
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>
> >>>
> >>
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
> >>>>>>>
> >>>>>>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <
> >>>> spmallette@gmail.com>
> >>>>>>> wrote:
> >>>>>>>
> >>>>>>>> I think i like that idea.  It would also force JIRA titles to be
> >>>> written
> >>>>>>>> better though so as to fit the flow of CHANGELOG....sometimes
> >> those
> >>>> are
> >>>>>>>> kinda slack.
> >>>>>>>>
> >>>>>>>> On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
> >>>>>>> matthew.h.frantz@gmail.com>
> >>>>>>>> wrote:
> >>>>>>>>
> >>>>>>>>> Correct.  We would make manual additions to the CHANGELOG only
> >> to
> >>>>>>> augment
> >>>>>>>>> the JIRA report in some way, either to explain non-JIRA
> >>> activities
> >>>> or
> >>>>>>> to
> >>>>>>>>> draw attention to particular JIRA issues that are significant
> >>> (and
> >>>> we
> >>>>>>>> would
> >>>>>>>>> cite the JIRA ticket from the CHANGELOG for those).  The
> >>>> definition of
> >>>>>>>>> "significant" is discretionary.
> >>>>>>>>>
> >>>>>>>>> On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
> >>>>>>> spmallette@gmail.com
> >>>>>>>>>
> >>>>>>>>> wrote:
> >>>>>>>>>
> >>>>>>>>>> Are you suggesting that on release we rectify the JIRA report
> >>>> with
> >>>>>>> the
> >>>>>>>>>> CHANGELOG?  In that way, if something was done by way of JIRA
> >>> we
> >>>>>>>> wouldn't
> >>>>>>>>>> have to enter a CHANGELOG entry manually, because on release
> >>> we'd
> >>>>>>> pick
> >>>>>>>> it
> >>>>>>>>>> up via the JIRA report?
> >>>>>>>>>>
> >>>>>>>>>> On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
> >>>>>>>> matthew.h.frantz@gmail.com
> >>>>>>>>>>
> >>>>>>>>>> wrote:
> >>>>>>>>>>
> >>>>>>>>>>> Perhaps in the release process we could generate a JIRA
> >>> report
> >>>> of
> >>>>>>>>> issues
> >>>>>>>>>>> marked as fixed in the specific version, and reserve the
> >>>> CHANGELOG
> >>>>>>>> for
> >>>>>>>>>>> significant changes and things that were not tracked
> >> through
> >>>> JIRA.
> >>>>>>>>>>>
> >>>>>>>>>>> On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
> >>>>>>>>> spmallette@gmail.com>
> >>>>>>>>>>> wrote:
> >>>>>>>>>>>
> >>>>>>>>>>>> We have typically treated CHANGELOG rather
> >>> unscientifically.
> >>>>>>> Make
> >>>>>>>> a
> >>>>>>>>>>> change
> >>>>>>>>>>>> of significance, then update the changelog for the
> >>>> appropriate
> >>>>>>>>> version.
> >>>>>>>>>>> I
> >>>>>>>>>>>> bat around the idea of including the issue ids all the
> >> time
> >>>> but
> >>>>>>>>> haven't
> >>>>>>>>>>>> wanted to start the trend of doing that.  Perhaps we do
> >>> that
> >>>> and
> >>>>>>>> make
> >>>>>>>>>> it
> >>>>>>>>>>>> optional?? Not sure how others feel on that matter.
> >>>>>>>>>>>>
> >>>>>>>>>>>> On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> >>>>>>>>>>> matthew.h.frantz@gmail.com>
> >>>>>>>>>>>> wrote:
> >>>>>>>>>>>>
> >>>>>>>>>>>>> I just merged my fix for TINKERPOP3-782 to both tp30
> >> and
> >>>>>>>> master.  I
> >>>>>>>>>>>> didn't
> >>>>>>>>>>>>> touch CHANGELOG.  Do we do that for every bug fix?  I
> >>> don't
> >>>>>>> see
> >>>>>>>>>>>> references
> >>>>>>>>>>>>> to JIRA artifacts in the CHANGELOG.
> >>>>>>>>>>>>>
> >>>>>>>>>>>>> On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> >>>>>>>>>>> spmallette@gmail.com>
> >>>>>>>
> >>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>
> >>>>>>>>>>>>>> Hi Matt,
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>> I have a PR currently targeted at tp30 (because it
> >> is a
> >>>>>>>> low-risk
> >>>>>>>>>> bug
> >>>>>>>>>>>>> fix).
> >>>>>>>>>>>>>>> I know that we don't necessarily code review
> >>> everything
> >>>>>>> that
> >>>>>>>>> goes
> >>>>>>>>>>> in,
> >>>>>>>>>>>>> but
> >>>>>>>>>>>>>>> since I'm relatively new, I wouldn't mind someone
> >>>> taking a
> >>>>>>>> peek
> >>>>>>>>>> at
> >>>>>>>>>>>> it,
> >>>>>>>>>>>>>> and
> >>>>>>>>>>>>>>> the verify that tp30 is the best target.
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>> Right - no official code review.  We pretty much tend
> >>> to
> >>>>>>> handle
> >>>>>>>>> it
> >>>>>>>>>> as
> >>>>>>>>>>>> you
> >>>>>>>>>>>>>> just did - on a case-by-case basis.
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> (I don't have permissions on the GitHub mirror for
> >>>>>>>>>>>>> incubating-tinkerpop.
> >>>>>>>>>>>>>>> Should I?)
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>> I don't think you should - I don't have permissions
> >>>> either.
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> Also, after it is merged to tp30, is the process
> >>> going
> >>>> to
> >>>>>>> be
> >>>>>>>>>> that I
> >>>>>>>>>>>>> would
> >>>>>>>>>>>>>>> also need to merge tp30 into master?  Or do we plan
> >>> to
> >>>>>>> merge
> >>>>>>>>> only
> >>>>>>>>>>>>>>> occasionally?
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>> I've been the only person committing things to tp30
> >> of
> >>>> any
> >>>>>>>>>> substance
> >>>>>>>>>>> so
> >>>>>>>>>>>>>> I've been doing it periodically, but generally
> >>> speaking,
> >>>> I'd
> >>>>>>>> say
> >>>>>>>>>> that
> >>>>>>>>>>>>> it's
> >>>>>>>>>>>>>> best if the person who commits to tp30 merges to
> >> master
> >>>>>>> (unless
> >>>>>>>>>> it's
> >>>>>>>>>>>>>> something pretty trivial).  In that way the person
> >> who
> >>>>>>>> committed
> >>>>>>>>> to
> >>>>>>>>>>>> tp30
> >>>>>>>>>>>>> is
> >>>>>>>>>>>>>> responsible for ensuring proper integration with
> >>> master.
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> >>>>>>>>>>>>> matthew.h.frantz@gmail.com>
> >>>>>>>
> >>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> I have a PR currently targeted at tp30 (because it
> >>> is a
> >>>>>>>>> low-risk
> >>>>>>>>>>> bug
> >>>>>>>>>>>>>> fix).
> >>>>>>>>>>>>>>> I know that we don't necessarily code review
> >>> everything
> >>>>>>> that
> >>>>>>>>> goes
> >>>>>>>>>>> in,
> >>>>>>>>>>>>> but
> >>>>>>>>>>>>>>> since I'm relatively new, I wouldn't mind someone
> >>>> taking a
> >>>>>>>> peek
> >>>>>>>>>> at
> >>>>>>>>>>>> it,
> >>>>>>>>>>>>>> and
> >>>>>>>>>>>>>>> the verify that tp30 is the best target.
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> (I don't have permissions on the GitHub mirror for
> >>>>>>>>>>>>> incubating-tinkerpop.
> >>>>>>>>>>>>>>> Should I?)
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> Also, after it is merged to tp30, is the process
> >>> going
> >>>> to
> >>>>>>> be
> >>>>>>>>>> that I
> >>>>>>>>>>>>> would
> >>>>>>>>>>>>>>> also need to merge tp30 into master?  Or do we plan
> >>> to
> >>>>>>> merge
> >>>>>>>>> only
> >>>>>>>>>>>>>>> occasionally?
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> >>>>>>>>>>>>> spmallette@gmail.com>
> >>>>>>>
> >>>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> Thanks JB - i'm familiar with semver and I think
> >>> the
> >>>>>>> idea
> >>>>>>>> is
> >>>>>>>>> to
> >>>>>>>>>>>>> follow
> >>>>>>>>>>>>>> it
> >>>>>>>>>>>>>>>> in principle, in that we will save API breaking
> >>>> change
> >>>>>>> for
> >>>>>>>>> the
> >>>>>>>>>>>>> "minor"
> >>>>>>>>>>>>>>>> version.   imo, we should stick to the three
> >> digit
> >>>>>>> system
> >>>>>>>> for
> >>>>>>>>>> now
> >>>>>>>>>>>>> but I
> >>>>>>>>>>>>>>>> guess it's worth considering what a "breaking
> >>> change"
> >>>>>>> is in
> >>>>>>>>> our
> >>>>>>>>>>>>>> context.
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> TinkerPop is "big" - it has both public and
> >>> internal
> >>>>>>> APIs.
> >>>>>>>>> if
> >>>>>>>>>> i
> >>>>>>>>>>>>> change
> >>>>>>>>>>>>>>> the
> >>>>>>>>>>>>>>>> package name of an internal API in a patch
> >>> release, I
> >>>>>>>>> wouldn't
> >>>>>>>>>>>> expect
> >>>>>>>>>>>>>>> that
> >>>>>>>>>>>>>>>> to break anyone and thus I'm not sure I'd
> >> consider
> >>>> that
> >>>>>>> a
> >>>>>>>>>>> breaking
> >>>>>>>>>>>>>> change
> >>>>>>>>>>>>>>>> (though it's always interesting to see how folks
> >>>> find
> >>>>>>>> their
> >>>>>>>>>> way
> >>>>>>>>>>>> into
> >>>>>>>>>>>>>>> using
> >>>>>>>>>>>>>>>> our internal classes) .  To me the "breaking
> >>> changes"
> >>>>>>> are
> >>>>>>>>> ones
> >>>>>>>>>>> that
> >>>>>>>>>>>>>> occur
> >>>>>>>>>>>>>>>> in the public classes (i.e. the ones people are
> >>>> likely
> >>>>>>> to
> >>>>>>>>> use)
> >>>>>>>>>>>> like:
> >>>>>>>>>>>>>>>> gremlin driver classes, structure API for
> >> vendors,
> >>>> step
> >>>>>>>>> classes
> >>>>>>>>>>> and
> >>>>>>>>>>>>>>>> GraphTraversal/GraphTraversalSource, etc.
> >> Changing
> >>>> those
> >>>>>>>>>> classes
> >>>>>>>>>>> in
> >>>>>>>>>>>>>> some
> >>>>>>>>>>>>>>>> way, would break the greatest percentage of
> >> users.
> >>>> I'm
> >>>>>>> not
> >>>>>>>>>> sure
> >>>>>>>>>>>> how
> >>>>>>>>>>>>>>> others
> >>>>>>>>>>>>>>>> feel, but I tend to think of "breaking change" in
> >>>> that
> >>>>>>> more
> >>>>>>>>>> fuzzy
> >>>>>>>>>>>>>>> fashion.
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>> On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste
> >>> Musso
> >>>> <
> >>>>>>>>>>>>>> jbmusso@gmail.com>
> >>>>>>>
> >>>>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> Related - have you considered using semantic
> >>>>>>> versioning
> >>>>>>>> [1]
> >>>>>>>>>>>>>>>>> (major.minor.patch)? Roughly, semver states
> >> that
> >>>>>>> breaking
> >>>>>>>>>>> changes
> >>>>>>>>>>>>>>>>> should bump major, new backward-compatible
> >>> features
> >>>>>>>> should
> >>>>>>>>>> bump
> >>>>>>>>>>>>> minor
> >>>>>>>>>>>>>>>>> while bug fixes should bump patch. It also
> >>> supports
> >>>>>>>>>> pre-release
> >>>>>>>>>>>>>>>>> version (-alpha, -incubating or -whatever
> >>>> suffixes).
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> In order to avoid having the first digit
> >> (major)
> >>>> being
> >>>>>>>>> bumped
> >>>>>>>>>>> too
> >>>>>>>>>>>>>>>>> often (TP3 shall remain TP3!), a variation
> >> could
> >>>> be:
> >>>>>>>>>>>>>>>>> marketing.major.minor.patch (downside to that
> >> is
> >>> 4
> >>>>>>> digits
> >>>>>>>>>>>>> versioning
> >>>>>>>>>>>>>>>>> instead of 3). For example, adding a new
> >> Gremlin
> >>>> step
> >>>>>>>> would
> >>>>>>>>>>> bump
> >>>>>>>>>>>>>> minor
> >>>>>>>>>>>>>>>>> while changing a step signature in a
> >>>>>>>> backward-incompatible
> >>>>>>>>>>> manner
> >>>>>>>>>>>>>>>>> would bump major.
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> semver is very popular in the
> >> JavaScript/Node.js
> >>>> world
> >>>>>>>> and
> >>>>>>>>>> used
> >>>>>>>>>>>>>>>>> extensively with npm (node package manager).
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> Just some thoughts.
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> Jean-Baptiste
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> [1] http://semver.org/
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>> On Mon, Jul 13, 2015 at 1:20 PM, Stephen
> >>> Mallette <
> >>>>>>>>>>>>>>> spmallette@gmail.com>
> >>>>>>>
> >>>>>>>>>>>>>>>>> wrote:
> >>>>>>>>>>>>>>>>>> I think it's worthwhile for us to do
> >> something
> >>>> we've
> >>>>>>>> not
> >>>>>>>>>>> really
> >>>>>>>>>>>>>> done
> >>>>>>>>>>>>>>>>> before
> >>>>>>>>>>>>>>>>>> with any of the TinkerPop projects: use
> >>>> branches. We
> >>>>>>>>>>> typically
> >>>>>>>>>>>>> tend
> >>>>>>>>>>>>>>> to
> >>>>>>>>>>>>>>>>> use
> >>>>>>>>>>>>>>>>>> branches for major refactoring that we might
> >>>> throw
> >>>>>>> out,
> >>>>>>>>> but
> >>>>>>>>>>> not
> >>>>>>>>>>>>>>> really
> >>>>>>>>>>>>>>>>> for
> >>>>>>>>>>>>>>>>>> release management. As we look past release
> >>>> 3.0.0, I
> >>>>>>>>> think
> >>>>>>>>>> we
> >>>>>>>>>>>>> will
> >>>>>>>>>>>>>>> want
> >>>>>>>>>>>>>>>>> to
> >>>>>>>>>>>>>>>>>> have the capability to do more frequent minor
> >>>>>>> releases
> >>>>>>>>>> (e.g.
> >>>>>>>>>>>>> 3.0.1,
> >>>>>>>>>>>>>>>>> 3.0.2,
> >>>>>>>>>>>>>>>>>> etc) while still being able to do work for a
> >>>> future
> >>>>>>>> 3.1.x
> >>>>>>>>>>> line
> >>>>>>>>>>>> of
> >>>>>>>>>>>>>>> code.
> >>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>> I think we can do this without too much
> >> change
> >>>> if we
> >>>>>>>>>>> introduce
> >>>>>>>>>>>> a
> >>>>>>>>>>>>>>> simple
> >>>>>>>>>>>>>>>>>> branch system.  Release branch rules would be
> >>>>>>> simple -
> >>>>>>>> we
> >>>>>>>>>>>> create
> >>>>>>>>>>>>> a
> >>>>>>>>>>>>>>> new
> >>>>>>>>>>>>>>>>>> branch from master called tp31 for the 3.1.x
> >>>> line of
> >>>>>>>>> code.
> >>>>>>>>>>> Any
> >>>>>>>>>>>>>>> changes
> >>>>>>>>>>>>>>>>>> that are "breaking", introduce significant
> >>> risk,
> >>>> a
> >>>>>>>>> "major"
> >>>>>>>>>>>>> feature,
> >>>>>>>>>>>>>>>> etc.
> >>>>>>>>>>>>>>>>>> would be committed there.  All other changes,
> >>> bug
> >>>>>>>> fixes,
> >>>>>>>>>>>>>> non-breaking
> >>>>>>>>>>>>>>>>>> refactoring of major APIs, "minor" features,
> >>> etc.
> >>>>>>> would
> >>>>>>>>>>> simply
> >>>>>>>>>>>>>> commit
> >>>>>>>>>>>>>>>> to
> >>>>>>>>>>>>>>>>>> master.  the master branch effectively
> >> becomes
> >>>> the
> >>>>>>>> 3.0.x
> >>>>>>>>>> line
> >>>>>>>>>>>> of
> >>>>>>>>>>>>>>> code.
> >>>>>>>>>>>>>>>>>> Under this approach the merge process is
> >> pretty
> >>>>>>> simple
> >>>>>>>> in
> >>>>>>>>>>> that
> >>>>>>>>>>>> we
> >>>>>>>>>>>>>>> just
> >>>>>>>>>>>>>>>>>> merge forward (i.e. master merges to to
> >> tp31).
> >>>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>>> When the day comes that we're ready to
> >> release
> >>>>>>> 3.1.0,
> >>>>>>>> we
> >>>>>>>>>>> merge
> >>>>>>>>>>>>> tp31
> >>>>>>>>>>>>>>>> back
> >>>>>>>>>>>>>>>>> to
> >>>>>>>>>>>>>>>>>> master and create tp32 and use the same model
> >>>> where
> >>>>>>> the
> >>>>>>>>>> 3.1.x
> >>>>>>>>>>>>> line
> >>>>>>>>>>>>>> is
> >>>>>>>>>>>>>>>>>> master and the 3.2.x line is tp32.  Of
> >> course,
> >>>> under
> >>>>>>>> this
> >>>>>>>>>>> model
> >>>>>>>>>>>>> we
> >>>>>>>>>>>>>>> are
> >>>>>>>>>>>>>>>>>> really supporting just the previous minor
> >>>> version,
> >>>>>>>> which
> >>>>>>>>>> for
> >>>>>>>>>>>>> right
> >>>>>>>>>>>>>>> now
> >>>>>>>>>>>>>>>>>> seems acceptable to me.  That's more than
> >> what
> >>>> we've
> >>>>>>>> ever
> >>>>>>>>>>>> really
> >>>>>>>>>>>>>> done
> >>>>>>>>>>>>>>>>> well,
> >>>>>>>>>>>>>>>>>> so that feels like a good starting point in
> >> my
> >>>> book.
> >>>>>>>>> After
> >>>>>>>>>>> we
> >>>>>>>>>>>>>>> release
> >>>>>>>>>>>>>>>>>> 3.1.0 we can revisit and decide if a more
> >>> complex
> >>>>>>>>> branching
> >>>>>>>>>>>>>> strategy
> >>>>>>>>>>>>>>> is
> >>>>>>>>>>>>>>>>>> needed.
> >>>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>>
> >>>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>
> >>>>>>>>
> >>>>>>>
> >>>>>>
> >>>>>>
> >>>>
> >>>
> >>
>
>

Re: branching after GA

[Marko Rodriguez <ok...@gmail.com>]

Hi Stephen,

First, I like the "breaking" label. Smart.

Second, RELEASE.asciidoc makes more sense than the README we have as the READEME is basically a weak "getting started" (point to docs at that point), build procedure (probably just add to RELEASE.asciidoc), and then the release process.

Thanks,
Marko.

http://markorodriguez.com

On Aug 10, 2015, at 5:11 AM, Stephen Mallette <sp...@gmail.com> wrote:

> I've merged this PR to tp30 - so we now have some guidelines on
> "contributing" which covers branches/release notes.  Thanks, matt, for
> getting the initial write up on that done.  I've made some minor
> modifications and included info on the "breaking" label for jira and some
> other bits.  I also move the "Issue Tracker Conventions" out of the README
> and over to CONTRIBUTING - seemed to make some more sense there.  Note the
> addition of the "breaking" label there. Please have a read:
> 
> https://github.com/apache/incubator-tinkerpop/blob/tp30/CONTRIBUTING.asciidoc
> 
> Note that I also adjusted the README regarding the "release process" in
> relation to "release note creation":
> 
> https://github.com/apache/incubator-tinkerpop/commit/c4c44ebb6e01f7178de16fb83f6d2fbe8d3590d0
> 
> Note sure how we want to call attention to "breaking" changes in there, but
> I guess we'll figure that out when the time comes.  As I look at README
> now, the "release process" looks out of place - I still kinda think that
> should just go in a new RELEASE.asciidoc file.
> 
> 
> On Fri, Jul 31, 2015 at 10:52 AM, Matt Frantz <ma...@gmail.com>
> wrote:
> 
>> RFC here:
>> https://github.com/apache/incubator-tinkerpop/pull/94
>> 
>> 
>> On Fri, Jul 31, 2015 at 3:02 AM, Stephen Mallette <sp...@gmail.com>
>> wrote:
>> 
>>> Hi David - agreed.  I hadn't done it yet as folks have been on vacation
>> and
>>> have not had a chance to weigh in on these ideas yet.
>>> 
>>> On Thu, Jul 30, 2015 at 9:45 PM, David Nalley <da...@gnsa.us> wrote:
>>> 
>>>> Guys, this thread contains awesome information - can we glean some of
>>>> it and put it on a web page or wiki page for other new folks so they
>>>> don't have to complete the question process.
>>>> 
>>>> On Fri, Jul 24, 2015 at 9:17 AM, Stephen Mallette <
>> spmallette@gmail.com>
>>>> wrote:
>>>>> It also just occurred to me that the 3.0.1 portion of the CHANGELOG
>>> needs
>>>>> to be replicated to the 3.1.0 section as the two may not be the same
>>>>> (though should be for the most part).
>>>>> 
>>>>> On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <
>>> spmallette@gmail.com>
>>>>> wrote:
>>>>> 
>>>>>> Yup - I was playing with that.  Let's see if Marko has any thoughts
>> on
>>>> the
>>>>>> matter.
>>>>>> 
>>>>>> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <
>>>> matthew.h.frantz@gmail.com>
>>>>>> wrote:
>>>>>> 
>>>>>>> JIRA has a configurable "Release Notes" report.
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>> 
>>> 
>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
>>>>>>> 
>>>>>>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <
>>>> spmallette@gmail.com>
>>>>>>> wrote:
>>>>>>> 
>>>>>>>> I think i like that idea.  It would also force JIRA titles to be
>>>> written
>>>>>>>> better though so as to fit the flow of CHANGELOG....sometimes
>> those
>>>> are
>>>>>>>> kinda slack.
>>>>>>>> 
>>>>>>>> On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
>>>>>>> matthew.h.frantz@gmail.com>
>>>>>>>> wrote:
>>>>>>>> 
>>>>>>>>> Correct.  We would make manual additions to the CHANGELOG only
>> to
>>>>>>> augment
>>>>>>>>> the JIRA report in some way, either to explain non-JIRA
>>> activities
>>>> or
>>>>>>> to
>>>>>>>>> draw attention to particular JIRA issues that are significant
>>> (and
>>>> we
>>>>>>>> would
>>>>>>>>> cite the JIRA ticket from the CHANGELOG for those).  The
>>>> definition of
>>>>>>>>> "significant" is discretionary.
>>>>>>>>> 
>>>>>>>>> On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
>>>>>>> spmallette@gmail.com
>>>>>>>>> 
>>>>>>>>> wrote:
>>>>>>>>> 
>>>>>>>>>> Are you suggesting that on release we rectify the JIRA report
>>>> with
>>>>>>> the
>>>>>>>>>> CHANGELOG?  In that way, if something was done by way of JIRA
>>> we
>>>>>>>> wouldn't
>>>>>>>>>> have to enter a CHANGELOG entry manually, because on release
>>> we'd
>>>>>>> pick
>>>>>>>> it
>>>>>>>>>> up via the JIRA report?
>>>>>>>>>> 
>>>>>>>>>> On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
>>>>>>>> matthew.h.frantz@gmail.com
>>>>>>>>>> 
>>>>>>>>>> wrote:
>>>>>>>>>> 
>>>>>>>>>>> Perhaps in the release process we could generate a JIRA
>>> report
>>>> of
>>>>>>>>> issues
>>>>>>>>>>> marked as fixed in the specific version, and reserve the
>>>> CHANGELOG
>>>>>>>> for
>>>>>>>>>>> significant changes and things that were not tracked
>> through
>>>> JIRA.
>>>>>>>>>>> 
>>>>>>>>>>> On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
>>>>>>>>> spmallette@gmail.com>
>>>>>>>>>>> wrote:
>>>>>>>>>>> 
>>>>>>>>>>>> We have typically treated CHANGELOG rather
>>> unscientifically.
>>>>>>> Make
>>>>>>>> a
>>>>>>>>>>> change
>>>>>>>>>>>> of significance, then update the changelog for the
>>>> appropriate
>>>>>>>>> version.
>>>>>>>>>>> I
>>>>>>>>>>>> bat around the idea of including the issue ids all the
>> time
>>>> but
>>>>>>>>> haven't
>>>>>>>>>>>> wanted to start the trend of doing that.  Perhaps we do
>>> that
>>>> and
>>>>>>>> make
>>>>>>>>>> it
>>>>>>>>>>>> optional?? Not sure how others feel on that matter.
>>>>>>>>>>>> 
>>>>>>>>>>>> On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
>>>>>>>>>>> matthew.h.frantz@gmail.com>
>>>>>>>>>>>> wrote:
>>>>>>>>>>>> 
>>>>>>>>>>>>> I just merged my fix for TINKERPOP3-782 to both tp30
>> and
>>>>>>>> master.  I
>>>>>>>>>>>> didn't
>>>>>>>>>>>>> touch CHANGELOG.  Do we do that for every bug fix?  I
>>> don't
>>>>>>> see
>>>>>>>>>>>> references
>>>>>>>>>>>>> to JIRA artifacts in the CHANGELOG.
>>>>>>>>>>>>> 
>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
>>>>>>>>>>> spmallette@gmail.com>
>>>>>>> 
>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Hi Matt,
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> I have a PR currently targeted at tp30 (because it
>> is a
>>>>>>>> low-risk
>>>>>>>>>> bug
>>>>>>>>>>>>> fix).
>>>>>>>>>>>>>>> I know that we don't necessarily code review
>>> everything
>>>>>>> that
>>>>>>>>> goes
>>>>>>>>>>> in,
>>>>>>>>>>>>> but
>>>>>>>>>>>>>>> since I'm relatively new, I wouldn't mind someone
>>>> taking a
>>>>>>>> peek
>>>>>>>>>> at
>>>>>>>>>>>> it,
>>>>>>>>>>>>>> and
>>>>>>>>>>>>>>> the verify that tp30 is the best target.
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Right - no official code review.  We pretty much tend
>>> to
>>>>>>> handle
>>>>>>>>> it
>>>>>>>>>> as
>>>>>>>>>>>> you
>>>>>>>>>>>>>> just did - on a case-by-case basis.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> (I don't have permissions on the GitHub mirror for
>>>>>>>>>>>>> incubating-tinkerpop.
>>>>>>>>>>>>>>> Should I?)
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> I don't think you should - I don't have permissions
>>>> either.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> Also, after it is merged to tp30, is the process
>>> going
>>>> to
>>>>>>> be
>>>>>>>>>> that I
>>>>>>>>>>>>> would
>>>>>>>>>>>>>>> also need to merge tp30 into master?  Or do we plan
>>> to
>>>>>>> merge
>>>>>>>>> only
>>>>>>>>>>>>>>> occasionally?
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> I've been the only person committing things to tp30
>> of
>>>> any
>>>>>>>>>> substance
>>>>>>>>>>> so
>>>>>>>>>>>>>> I've been doing it periodically, but generally
>>> speaking,
>>>> I'd
>>>>>>>> say
>>>>>>>>>> that
>>>>>>>>>>>>> it's
>>>>>>>>>>>>>> best if the person who commits to tp30 merges to
>> master
>>>>>>> (unless
>>>>>>>>>> it's
>>>>>>>>>>>>>> something pretty trivial).  In that way the person
>> who
>>>>>>>> committed
>>>>>>>>> to
>>>>>>>>>>>> tp30
>>>>>>>>>>>>> is
>>>>>>>>>>>>>> responsible for ensuring proper integration with
>>> master.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
>>>>>>>>>>>>> matthew.h.frantz@gmail.com>
>>>>>>> 
>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> I have a PR currently targeted at tp30 (because it
>>> is a
>>>>>>>>> low-risk
>>>>>>>>>>> bug
>>>>>>>>>>>>>> fix).
>>>>>>>>>>>>>>> I know that we don't necessarily code review
>>> everything
>>>>>>> that
>>>>>>>>> goes
>>>>>>>>>>> in,
>>>>>>>>>>>>> but
>>>>>>>>>>>>>>> since I'm relatively new, I wouldn't mind someone
>>>> taking a
>>>>>>>> peek
>>>>>>>>>> at
>>>>>>>>>>>> it,
>>>>>>>>>>>>>> and
>>>>>>>>>>>>>>> the verify that tp30 is the best target.
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> (I don't have permissions on the GitHub mirror for
>>>>>>>>>>>>> incubating-tinkerpop.
>>>>>>>>>>>>>>> Should I?)
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> Also, after it is merged to tp30, is the process
>>> going
>>>> to
>>>>>>> be
>>>>>>>>>> that I
>>>>>>>>>>>>> would
>>>>>>>>>>>>>>> also need to merge tp30 into master?  Or do we plan
>>> to
>>>>>>> merge
>>>>>>>>> only
>>>>>>>>>>>>>>> occasionally?
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
>>>>>>>>>>>>> spmallette@gmail.com>
>>>>>>> 
>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> Thanks JB - i'm familiar with semver and I think
>>> the
>>>>>>> idea
>>>>>>>> is
>>>>>>>>> to
>>>>>>>>>>>>> follow
>>>>>>>>>>>>>> it
>>>>>>>>>>>>>>>> in principle, in that we will save API breaking
>>>> change
>>>>>>> for
>>>>>>>>> the
>>>>>>>>>>>>> "minor"
>>>>>>>>>>>>>>>> version.   imo, we should stick to the three
>> digit
>>>>>>> system
>>>>>>>> for
>>>>>>>>>> now
>>>>>>>>>>>>> but I
>>>>>>>>>>>>>>>> guess it's worth considering what a "breaking
>>> change"
>>>>>>> is in
>>>>>>>>> our
>>>>>>>>>>>>>> context.
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> TinkerPop is "big" - it has both public and
>>> internal
>>>>>>> APIs.
>>>>>>>>> if
>>>>>>>>>> i
>>>>>>>>>>>>> change
>>>>>>>>>>>>>>> the
>>>>>>>>>>>>>>>> package name of an internal API in a patch
>>> release, I
>>>>>>>>> wouldn't
>>>>>>>>>>>> expect
>>>>>>>>>>>>>>> that
>>>>>>>>>>>>>>>> to break anyone and thus I'm not sure I'd
>> consider
>>>> that
>>>>>>> a
>>>>>>>>>>> breaking
>>>>>>>>>>>>>> change
>>>>>>>>>>>>>>>> (though it's always interesting to see how folks
>>>> find
>>>>>>>> their
>>>>>>>>>> way
>>>>>>>>>>>> into
>>>>>>>>>>>>>>> using
>>>>>>>>>>>>>>>> our internal classes) .  To me the "breaking
>>> changes"
>>>>>>> are
>>>>>>>>> ones
>>>>>>>>>>> that
>>>>>>>>>>>>>> occur
>>>>>>>>>>>>>>>> in the public classes (i.e. the ones people are
>>>> likely
>>>>>>> to
>>>>>>>>> use)
>>>>>>>>>>>> like:
>>>>>>>>>>>>>>>> gremlin driver classes, structure API for
>> vendors,
>>>> step
>>>>>>>>> classes
>>>>>>>>>>> and
>>>>>>>>>>>>>>>> GraphTraversal/GraphTraversalSource, etc.
>> Changing
>>>> those
>>>>>>>>>> classes
>>>>>>>>>>> in
>>>>>>>>>>>>>> some
>>>>>>>>>>>>>>>> way, would break the greatest percentage of
>> users.
>>>> I'm
>>>>>>> not
>>>>>>>>>> sure
>>>>>>>>>>>> how
>>>>>>>>>>>>>>> others
>>>>>>>>>>>>>>>> feel, but I tend to think of "breaking change" in
>>>> that
>>>>>>> more
>>>>>>>>>> fuzzy
>>>>>>>>>>>>>>> fashion.
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste
>>> Musso
>>>> <
>>>>>>>>>>>>>> jbmusso@gmail.com>
>>>>>>> 
>>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> Related - have you considered using semantic
>>>>>>> versioning
>>>>>>>> [1]
>>>>>>>>>>>>>>>>> (major.minor.patch)? Roughly, semver states
>> that
>>>>>>> breaking
>>>>>>>>>>> changes
>>>>>>>>>>>>>>>>> should bump major, new backward-compatible
>>> features
>>>>>>>> should
>>>>>>>>>> bump
>>>>>>>>>>>>> minor
>>>>>>>>>>>>>>>>> while bug fixes should bump patch. It also
>>> supports
>>>>>>>>>> pre-release
>>>>>>>>>>>>>>>>> version (-alpha, -incubating or -whatever
>>>> suffixes).
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> In order to avoid having the first digit
>> (major)
>>>> being
>>>>>>>>> bumped
>>>>>>>>>>> too
>>>>>>>>>>>>>>>>> often (TP3 shall remain TP3!), a variation
>> could
>>>> be:
>>>>>>>>>>>>>>>>> marketing.major.minor.patch (downside to that
>> is
>>> 4
>>>>>>> digits
>>>>>>>>>>>>> versioning
>>>>>>>>>>>>>>>>> instead of 3). For example, adding a new
>> Gremlin
>>>> step
>>>>>>>> would
>>>>>>>>>>> bump
>>>>>>>>>>>>>> minor
>>>>>>>>>>>>>>>>> while changing a step signature in a
>>>>>>>> backward-incompatible
>>>>>>>>>>> manner
>>>>>>>>>>>>>>>>> would bump major.
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> semver is very popular in the
>> JavaScript/Node.js
>>>> world
>>>>>>>> and
>>>>>>>>>> used
>>>>>>>>>>>>>>>>> extensively with npm (node package manager).
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> Just some thoughts.
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> Jean-Baptiste
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> [1] http://semver.org/
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>> On Mon, Jul 13, 2015 at 1:20 PM, Stephen
>>> Mallette <
>>>>>>>>>>>>>>> spmallette@gmail.com>
>>>>>>> 
>>>>>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>>>>>>> I think it's worthwhile for us to do
>> something
>>>> we've
>>>>>>>> not
>>>>>>>>>>> really
>>>>>>>>>>>>>> done
>>>>>>>>>>>>>>>>> before
>>>>>>>>>>>>>>>>>> with any of the TinkerPop projects: use
>>>> branches. We
>>>>>>>>>>> typically
>>>>>>>>>>>>> tend
>>>>>>>>>>>>>>> to
>>>>>>>>>>>>>>>>> use
>>>>>>>>>>>>>>>>>> branches for major refactoring that we might
>>>> throw
>>>>>>> out,
>>>>>>>>> but
>>>>>>>>>>> not
>>>>>>>>>>>>>>> really
>>>>>>>>>>>>>>>>> for
>>>>>>>>>>>>>>>>>> release management. As we look past release
>>>> 3.0.0, I
>>>>>>>>> think
>>>>>>>>>> we
>>>>>>>>>>>>> will
>>>>>>>>>>>>>>> want
>>>>>>>>>>>>>>>>> to
>>>>>>>>>>>>>>>>>> have the capability to do more frequent minor
>>>>>>> releases
>>>>>>>>>> (e.g.
>>>>>>>>>>>>> 3.0.1,
>>>>>>>>>>>>>>>>> 3.0.2,
>>>>>>>>>>>>>>>>>> etc) while still being able to do work for a
>>>> future
>>>>>>>> 3.1.x
>>>>>>>>>>> line
>>>>>>>>>>>> of
>>>>>>>>>>>>>>> code.
>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>> I think we can do this without too much
>> change
>>>> if we
>>>>>>>>>>> introduce
>>>>>>>>>>>> a
>>>>>>>>>>>>>>> simple
>>>>>>>>>>>>>>>>>> branch system.  Release branch rules would be
>>>>>>> simple -
>>>>>>>> we
>>>>>>>>>>>> create
>>>>>>>>>>>>> a
>>>>>>>>>>>>>>> new
>>>>>>>>>>>>>>>>>> branch from master called tp31 for the 3.1.x
>>>> line of
>>>>>>>>> code.
>>>>>>>>>>> Any
>>>>>>>>>>>>>>> changes
>>>>>>>>>>>>>>>>>> that are "breaking", introduce significant
>>> risk,
>>>> a
>>>>>>>>> "major"
>>>>>>>>>>>>> feature,
>>>>>>>>>>>>>>>> etc.
>>>>>>>>>>>>>>>>>> would be committed there.  All other changes,
>>> bug
>>>>>>>> fixes,
>>>>>>>>>>>>>> non-breaking
>>>>>>>>>>>>>>>>>> refactoring of major APIs, "minor" features,
>>> etc.
>>>>>>> would
>>>>>>>>>>> simply
>>>>>>>>>>>>>> commit
>>>>>>>>>>>>>>>> to
>>>>>>>>>>>>>>>>>> master.  the master branch effectively
>> becomes
>>>> the
>>>>>>>> 3.0.x
>>>>>>>>>> line
>>>>>>>>>>>> of
>>>>>>>>>>>>>>> code.
>>>>>>>>>>>>>>>>>> Under this approach the merge process is
>> pretty
>>>>>>> simple
>>>>>>>> in
>>>>>>>>>>> that
>>>>>>>>>>>> we
>>>>>>>>>>>>>>> just
>>>>>>>>>>>>>>>>>> merge forward (i.e. master merges to to
>> tp31).
>>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>>>> When the day comes that we're ready to
>> release
>>>>>>> 3.1.0,
>>>>>>>> we
>>>>>>>>>>> merge
>>>>>>>>>>>>> tp31
>>>>>>>>>>>>>>>> back
>>>>>>>>>>>>>>>>> to
>>>>>>>>>>>>>>>>>> master and create tp32 and use the same model
>>>> where
>>>>>>> the
>>>>>>>>>> 3.1.x
>>>>>>>>>>>>> line
>>>>>>>>>>>>>> is
>>>>>>>>>>>>>>>>>> master and the 3.2.x line is tp32.  Of
>> course,
>>>> under
>>>>>>>> this
>>>>>>>>>>> model
>>>>>>>>>>>>> we
>>>>>>>>>>>>>>> are
>>>>>>>>>>>>>>>>>> really supporting just the previous minor
>>>> version,
>>>>>>>> which
>>>>>>>>>> for
>>>>>>>>>>>>> right
>>>>>>>>>>>>>>> now
>>>>>>>>>>>>>>>>>> seems acceptable to me.  That's more than
>> what
>>>> we've
>>>>>>>> ever
>>>>>>>>>>>> really
>>>>>>>>>>>>>> done
>>>>>>>>>>>>>>>>> well,
>>>>>>>>>>>>>>>>>> so that feels like a good starting point in
>> my
>>>> book.
>>>>>>>>> After
>>>>>>>>>>> we
>>>>>>>>>>>>>>> release
>>>>>>>>>>>>>>>>>> 3.1.0 we can revisit and decide if a more
>>> complex
>>>>>>>>> branching
>>>>>>>>>>>>>> strategy
>>>>>>>>>>>>>>> is
>>>>>>>>>>>>>>>>>> needed.
>>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>> 
>>>>>>>> 
>>>>>>> 
>>>>>> 
>>>>>> 
>>>> 
>>> 
>> 

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

I've merged this PR to tp30 - so we now have some guidelines on
"contributing" which covers branches/release notes.  Thanks, matt, for
getting the initial write up on that done.  I've made some minor
modifications and included info on the "breaking" label for jira and some
other bits.  I also move the "Issue Tracker Conventions" out of the README
and over to CONTRIBUTING - seemed to make some more sense there.  Note the
addition of the "breaking" label there. Please have a read:

https://github.com/apache/incubator-tinkerpop/blob/tp30/CONTRIBUTING.asciidoc

Note that I also adjusted the README regarding the "release process" in
relation to "release note creation":

https://github.com/apache/incubator-tinkerpop/commit/c4c44ebb6e01f7178de16fb83f6d2fbe8d3590d0

Note sure how we want to call attention to "breaking" changes in there, but
I guess we'll figure that out when the time comes.  As I look at README
now, the "release process" looks out of place - I still kinda think that
should just go in a new RELEASE.asciidoc file.


On Fri, Jul 31, 2015 at 10:52 AM, Matt Frantz <ma...@gmail.com>
wrote:

> RFC here:
> https://github.com/apache/incubator-tinkerpop/pull/94
>
>
> On Fri, Jul 31, 2015 at 3:02 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > Hi David - agreed.  I hadn't done it yet as folks have been on vacation
> and
> > have not had a chance to weigh in on these ideas yet.
> >
> > On Thu, Jul 30, 2015 at 9:45 PM, David Nalley <da...@gnsa.us> wrote:
> >
> > > Guys, this thread contains awesome information - can we glean some of
> > > it and put it on a web page or wiki page for other new folks so they
> > > don't have to complete the question process.
> > >
> > > On Fri, Jul 24, 2015 at 9:17 AM, Stephen Mallette <
> spmallette@gmail.com>
> > > wrote:
> > > > It also just occurred to me that the 3.0.1 portion of the CHANGELOG
> > needs
> > > > to be replicated to the 3.1.0 section as the two may not be the same
> > > > (though should be for the most part).
> > > >
> > > > On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <
> > spmallette@gmail.com>
> > > > wrote:
> > > >
> > > >> Yup - I was playing with that.  Let's see if Marko has any thoughts
> on
> > > the
> > > >> matter.
> > > >>
> > > >> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <
> > > matthew.h.frantz@gmail.com>
> > > >> wrote:
> > > >>
> > > >>> JIRA has a configurable "Release Notes" report.
> > > >>>
> > > >>>
> > > >>>
> > >
> >
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
> > > >>>
> > > >>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <
> > > spmallette@gmail.com>
> > > >>> wrote:
> > > >>>
> > > >>> > I think i like that idea.  It would also force JIRA titles to be
> > > written
> > > >>> > better though so as to fit the flow of CHANGELOG....sometimes
> those
> > > are
> > > >>> > kinda slack.
> > > >>> >
> > > >>> > On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
> > > >>> matthew.h.frantz@gmail.com>
> > > >>> > wrote:
> > > >>> >
> > > >>> > > Correct.  We would make manual additions to the CHANGELOG only
> to
> > > >>> augment
> > > >>> > > the JIRA report in some way, either to explain non-JIRA
> > activities
> > > or
> > > >>> to
> > > >>> > > draw attention to particular JIRA issues that are significant
> > (and
> > > we
> > > >>> > would
> > > >>> > > cite the JIRA ticket from the CHANGELOG for those).  The
> > > definition of
> > > >>> > > "significant" is discretionary.
> > > >>> > >
> > > >>> > > On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
> > > >>> spmallette@gmail.com
> > > >>> > >
> > > >>> > > wrote:
> > > >>> > >
> > > >>> > > > Are you suggesting that on release we rectify the JIRA report
> > > with
> > > >>> the
> > > >>> > > > CHANGELOG?  In that way, if something was done by way of JIRA
> > we
> > > >>> > wouldn't
> > > >>> > > > have to enter a CHANGELOG entry manually, because on release
> > we'd
> > > >>> pick
> > > >>> > it
> > > >>> > > > up via the JIRA report?
> > > >>> > > >
> > > >>> > > > On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
> > > >>> > matthew.h.frantz@gmail.com
> > > >>> > > >
> > > >>> > > > wrote:
> > > >>> > > >
> > > >>> > > > > Perhaps in the release process we could generate a JIRA
> > report
> > > of
> > > >>> > > issues
> > > >>> > > > > marked as fixed in the specific version, and reserve the
> > > CHANGELOG
> > > >>> > for
> > > >>> > > > > significant changes and things that were not tracked
> through
> > > JIRA.
> > > >>> > > > >
> > > >>> > > > > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
> > > >>> > > spmallette@gmail.com>
> > > >>> > > > > wrote:
> > > >>> > > > >
> > > >>> > > > > > We have typically treated CHANGELOG rather
> > unscientifically.
> > > >>> Make
> > > >>> > a
> > > >>> > > > > change
> > > >>> > > > > > of significance, then update the changelog for the
> > > appropriate
> > > >>> > > version.
> > > >>> > > > > I
> > > >>> > > > > > bat around the idea of including the issue ids all the
> time
> > > but
> > > >>> > > haven't
> > > >>> > > > > > wanted to start the trend of doing that.  Perhaps we do
> > that
> > > and
> > > >>> > make
> > > >>> > > > it
> > > >>> > > > > > optional?? Not sure how others feel on that matter.
> > > >>> > > > > >
> > > >>> > > > > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> > > >>> > > > > matthew.h.frantz@gmail.com>
> > > >>> > > > > > wrote:
> > > >>> > > > > >
> > > >>> > > > > > > I just merged my fix for TINKERPOP3-782 to both tp30
> and
> > > >>> > master.  I
> > > >>> > > > > > didn't
> > > >>> > > > > > > touch CHANGELOG.  Do we do that for every bug fix?  I
> > don't
> > > >>> see
> > > >>> > > > > > references
> > > >>> > > > > > > to JIRA artifacts in the CHANGELOG.
> > > >>> > > > > > >
> > > >>> > > > > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> > > >>> > > > > spmallette@gmail.com>
> > > >>>
> > > >>> > > > > > > wrote:
> > > >>> > > > > > >
> > > >>> > > > > > > > Hi Matt,
> > > >>> > > > > > > >
> > > >>> > > > > > > > I have a PR currently targeted at tp30 (because it
> is a
> > > >>> > low-risk
> > > >>> > > > bug
> > > >>> > > > > > > fix).
> > > >>> > > > > > > > > I know that we don't necessarily code review
> > everything
> > > >>> that
> > > >>> > > goes
> > > >>> > > > > in,
> > > >>> > > > > > > but
> > > >>> > > > > > > > > since I'm relatively new, I wouldn't mind someone
> > > taking a
> > > >>> > peek
> > > >>> > > > at
> > > >>> > > > > > it,
> > > >>> > > > > > > > and
> > > >>> > > > > > > > > the verify that tp30 is the best target.
> > > >>> > > > > > > > >
> > > >>> > > > > > > >
> > > >>> > > > > > > > Right - no official code review.  We pretty much tend
> > to
> > > >>> handle
> > > >>> > > it
> > > >>> > > > as
> > > >>> > > > > > you
> > > >>> > > > > > > > just did - on a case-by-case basis.
> > > >>> > > > > > > >
> > > >>> > > > > > > >
> > > >>> > > > > > > > > (I don't have permissions on the GitHub mirror for
> > > >>> > > > > > > incubating-tinkerpop.
> > > >>> > > > > > > > > Should I?)
> > > >>> > > > > > > > >
> > > >>> > > > > > > >
> > > >>> > > > > > > > I don't think you should - I don't have permissions
> > > either.
> > > >>> > > > > > > >
> > > >>> > > > > > > >
> > > >>> > > > > > > > > Also, after it is merged to tp30, is the process
> > going
> > > to
> > > >>> be
> > > >>> > > > that I
> > > >>> > > > > > > would
> > > >>> > > > > > > > > also need to merge tp30 into master?  Or do we plan
> > to
> > > >>> merge
> > > >>> > > only
> > > >>> > > > > > > > > occasionally?
> > > >>> > > > > > > >
> > > >>> > > > > > > >
> > > >>> > > > > > > > I've been the only person committing things to tp30
> of
> > > any
> > > >>> > > > substance
> > > >>> > > > > so
> > > >>> > > > > > > > I've been doing it periodically, but generally
> > speaking,
> > > I'd
> > > >>> > say
> > > >>> > > > that
> > > >>> > > > > > > it's
> > > >>> > > > > > > > best if the person who commits to tp30 merges to
> master
> > > >>> (unless
> > > >>> > > > it's
> > > >>> > > > > > > > something pretty trivial).  In that way the person
> who
> > > >>> > committed
> > > >>> > > to
> > > >>> > > > > > tp30
> > > >>> > > > > > > is
> > > >>> > > > > > > > responsible for ensuring proper integration with
> > master.
> > > >>> > > > > > > >
> > > >>> > > > > > > >
> > > >>> > > > > > > >
> > > >>> > > > > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> > > >>> > > > > > > matthew.h.frantz@gmail.com>
> > > >>>
> > > >>> > > > > > > > wrote:
> > > >>> > > > > > > >
> > > >>> > > > > > > > > I have a PR currently targeted at tp30 (because it
> > is a
> > > >>> > > low-risk
> > > >>> > > > > bug
> > > >>> > > > > > > > fix).
> > > >>> > > > > > > > > I know that we don't necessarily code review
> > everything
> > > >>> that
> > > >>> > > goes
> > > >>> > > > > in,
> > > >>> > > > > > > but
> > > >>> > > > > > > > > since I'm relatively new, I wouldn't mind someone
> > > taking a
> > > >>> > peek
> > > >>> > > > at
> > > >>> > > > > > it,
> > > >>> > > > > > > > and
> > > >>> > > > > > > > > the verify that tp30 is the best target.
> > > >>> > > > > > > > >
> > > >>> > > > > > > > > (I don't have permissions on the GitHub mirror for
> > > >>> > > > > > > incubating-tinkerpop.
> > > >>> > > > > > > > > Should I?)
> > > >>> > > > > > > > >
> > > >>> > > > > > > > > Also, after it is merged to tp30, is the process
> > going
> > > to
> > > >>> be
> > > >>> > > > that I
> > > >>> > > > > > > would
> > > >>> > > > > > > > > also need to merge tp30 into master?  Or do we plan
> > to
> > > >>> merge
> > > >>> > > only
> > > >>> > > > > > > > > occasionally?
> > > >>> > > > > > > > >
> > > >>> > > > > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> > > >>> > > > > > > spmallette@gmail.com>
> > > >>>
> > > >>> > > > > > > > > wrote:
> > > >>> > > > > > > > >
> > > >>> > > > > > > > > > Thanks JB - i'm familiar with semver and I think
> > the
> > > >>> idea
> > > >>> > is
> > > >>> > > to
> > > >>> > > > > > > follow
> > > >>> > > > > > > > it
> > > >>> > > > > > > > > > in principle, in that we will save API breaking
> > > change
> > > >>> for
> > > >>> > > the
> > > >>> > > > > > > "minor"
> > > >>> > > > > > > > > > version.   imo, we should stick to the three
> digit
> > > >>> system
> > > >>> > for
> > > >>> > > > now
> > > >>> > > > > > > but I
> > > >>> > > > > > > > > > guess it's worth considering what a "breaking
> > change"
> > > >>> is in
> > > >>> > > our
> > > >>> > > > > > > > context.
> > > >>> > > > > > > > > >
> > > >>> > > > > > > > > > TinkerPop is "big" - it has both public and
> > internal
> > > >>> APIs.
> > > >>> > > if
> > > >>> > > > i
> > > >>> > > > > > > change
> > > >>> > > > > > > > > the
> > > >>> > > > > > > > > > package name of an internal API in a patch
> > release, I
> > > >>> > > wouldn't
> > > >>> > > > > > expect
> > > >>> > > > > > > > > that
> > > >>> > > > > > > > > > to break anyone and thus I'm not sure I'd
> consider
> > > that
> > > >>> a
> > > >>> > > > > breaking
> > > >>> > > > > > > > change
> > > >>> > > > > > > > > >  (though it's always interesting to see how folks
> > > find
> > > >>> > their
> > > >>> > > > way
> > > >>> > > > > > into
> > > >>> > > > > > > > > using
> > > >>> > > > > > > > > > our internal classes) .  To me the "breaking
> > changes"
> > > >>> are
> > > >>> > > ones
> > > >>> > > > > that
> > > >>> > > > > > > > occur
> > > >>> > > > > > > > > > in the public classes (i.e. the ones people are
> > > likely
> > > >>> to
> > > >>> > > use)
> > > >>> > > > > > like:
> > > >>> > > > > > > > > > gremlin driver classes, structure API for
> vendors,
> > > step
> > > >>> > > classes
> > > >>> > > > > and
> > > >>> > > > > > > > > > GraphTraversal/GraphTraversalSource, etc.
> Changing
> > > those
> > > >>> > > > classes
> > > >>> > > > > in
> > > >>> > > > > > > > some
> > > >>> > > > > > > > > > way, would break the greatest percentage of
> users.
> > > I'm
> > > >>> not
> > > >>> > > > sure
> > > >>> > > > > > how
> > > >>> > > > > > > > > others
> > > >>> > > > > > > > > > feel, but I tend to think of "breaking change" in
> > > that
> > > >>> more
> > > >>> > > > fuzzy
> > > >>> > > > > > > > > fashion.
> > > >>> > > > > > > > > >
> > > >>> > > > > > > > > >
> > > >>> > > > > > > > > >
> > > >>> > > > > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste
> > Musso
> > > <
> > > >>> > > > > > > > jbmusso@gmail.com>
> > > >>>
> > > >>> > > > > > > > > > wrote:
> > > >>> > > > > > > > > >
> > > >>> > > > > > > > > > > Related - have you considered using semantic
> > > >>> versioning
> > > >>> > [1]
> > > >>> > > > > > > > > > > (major.minor.patch)? Roughly, semver states
> that
> > > >>> breaking
> > > >>> > > > > changes
> > > >>> > > > > > > > > > > should bump major, new backward-compatible
> > features
> > > >>> > should
> > > >>> > > > bump
> > > >>> > > > > > > minor
> > > >>> > > > > > > > > > > while bug fixes should bump patch. It also
> > supports
> > > >>> > > > pre-release
> > > >>> > > > > > > > > > > version (-alpha, -incubating or -whatever
> > > suffixes).
> > > >>> > > > > > > > > > >
> > > >>> > > > > > > > > > > In order to avoid having the first digit
> (major)
> > > being
> > > >>> > > bumped
> > > >>> > > > > too
> > > >>> > > > > > > > > > > often (TP3 shall remain TP3!), a variation
> could
> > > be:
> > > >>> > > > > > > > > > > marketing.major.minor.patch (downside to that
> is
> > 4
> > > >>> digits
> > > >>> > > > > > > versioning
> > > >>> > > > > > > > > > > instead of 3). For example, adding a new
> Gremlin
> > > step
> > > >>> > would
> > > >>> > > > > bump
> > > >>> > > > > > > > minor
> > > >>> > > > > > > > > > > while changing a step signature in a
> > > >>> > backward-incompatible
> > > >>> > > > > manner
> > > >>> > > > > > > > > > > would bump major.
> > > >>> > > > > > > > > > >
> > > >>> > > > > > > > > > > semver is very popular in the
> JavaScript/Node.js
> > > world
> > > >>> > and
> > > >>> > > > used
> > > >>> > > > > > > > > > > extensively with npm (node package manager).
> > > >>> > > > > > > > > > >
> > > >>> > > > > > > > > > > Just some thoughts.
> > > >>> > > > > > > > > > >
> > > >>> > > > > > > > > > > Jean-Baptiste
> > > >>> > > > > > > > > > >
> > > >>> > > > > > > > > > > [1] http://semver.org/
> > > >>> > > > > > > > > > >
> > > >>> > > > > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen
> > Mallette <
> > > >>> > > > > > > > > spmallette@gmail.com>
> > > >>>
> > > >>> > > > > > > > > > > wrote:
> > > >>> > > > > > > > > > > > I think it's worthwhile for us to do
> something
> > > we've
> > > >>> > not
> > > >>> > > > > really
> > > >>> > > > > > > > done
> > > >>> > > > > > > > > > > before
> > > >>> > > > > > > > > > > > with any of the TinkerPop projects: use
> > > branches. We
> > > >>> > > > > typically
> > > >>> > > > > > > tend
> > > >>> > > > > > > > > to
> > > >>> > > > > > > > > > > use
> > > >>> > > > > > > > > > > > branches for major refactoring that we might
> > > throw
> > > >>> out,
> > > >>> > > but
> > > >>> > > > > not
> > > >>> > > > > > > > > really
> > > >>> > > > > > > > > > > for
> > > >>> > > > > > > > > > > > release management. As we look past release
> > > 3.0.0, I
> > > >>> > > think
> > > >>> > > > we
> > > >>> > > > > > > will
> > > >>> > > > > > > > > want
> > > >>> > > > > > > > > > > to
> > > >>> > > > > > > > > > > > have the capability to do more frequent minor
> > > >>> releases
> > > >>> > > > (e.g.
> > > >>> > > > > > > 3.0.1,
> > > >>> > > > > > > > > > > 3.0.2,
> > > >>> > > > > > > > > > > > etc) while still being able to do work for a
> > > future
> > > >>> > 3.1.x
> > > >>> > > > > line
> > > >>> > > > > > of
> > > >>> > > > > > > > > code.
> > > >>> > > > > > > > > > > >
> > > >>> > > > > > > > > > > > I think we can do this without too much
> change
> > > if we
> > > >>> > > > > introduce
> > > >>> > > > > > a
> > > >>> > > > > > > > > simple
> > > >>> > > > > > > > > > > > branch system.  Release branch rules would be
> > > >>> simple -
> > > >>> > we
> > > >>> > > > > > create
> > > >>> > > > > > > a
> > > >>> > > > > > > > > new
> > > >>> > > > > > > > > > > > branch from master called tp31 for the 3.1.x
> > > line of
> > > >>> > > code.
> > > >>> > > > > Any
> > > >>> > > > > > > > > changes
> > > >>> > > > > > > > > > > > that are "breaking", introduce significant
> > risk,
> > > a
> > > >>> > > "major"
> > > >>> > > > > > > feature,
> > > >>> > > > > > > > > > etc.
> > > >>> > > > > > > > > > > > would be committed there.  All other changes,
> > bug
> > > >>> > fixes,
> > > >>> > > > > > > > non-breaking
> > > >>> > > > > > > > > > > > refactoring of major APIs, "minor" features,
> > etc.
> > > >>> would
> > > >>> > > > > simply
> > > >>> > > > > > > > commit
> > > >>> > > > > > > > > > to
> > > >>> > > > > > > > > > > > master.  the master branch effectively
> becomes
> > > the
> > > >>> > 3.0.x
> > > >>> > > > line
> > > >>> > > > > > of
> > > >>> > > > > > > > > code.
> > > >>> > > > > > > > > > > > Under this approach the merge process is
> pretty
> > > >>> simple
> > > >>> > in
> > > >>> > > > > that
> > > >>> > > > > > we
> > > >>> > > > > > > > > just
> > > >>> > > > > > > > > > > > merge forward (i.e. master merges to to
> tp31).
> > > >>> > > > > > > > > > > >
> > > >>> > > > > > > > > > > > When the day comes that we're ready to
> release
> > > >>> 3.1.0,
> > > >>> > we
> > > >>> > > > > merge
> > > >>> > > > > > > tp31
> > > >>> > > > > > > > > > back
> > > >>> > > > > > > > > > > to
> > > >>> > > > > > > > > > > > master and create tp32 and use the same model
> > > where
> > > >>> the
> > > >>> > > > 3.1.x
> > > >>> > > > > > > line
> > > >>> > > > > > > > is
> > > >>> > > > > > > > > > > > master and the 3.2.x line is tp32.  Of
> course,
> > > under
> > > >>> > this
> > > >>> > > > > model
> > > >>> > > > > > > we
> > > >>> > > > > > > > > are
> > > >>> > > > > > > > > > > > really supporting just the previous minor
> > > version,
> > > >>> > which
> > > >>> > > > for
> > > >>> > > > > > > right
> > > >>> > > > > > > > > now
> > > >>> > > > > > > > > > > > seems acceptable to me.  That's more than
> what
> > > we've
> > > >>> > ever
> > > >>> > > > > > really
> > > >>> > > > > > > > done
> > > >>> > > > > > > > > > > well,
> > > >>> > > > > > > > > > > > so that feels like a good starting point in
> my
> > > book.
> > > >>> > > After
> > > >>> > > > > we
> > > >>> > > > > > > > > release
> > > >>> > > > > > > > > > > > 3.1.0 we can revisit and decide if a more
> > complex
> > > >>> > > branching
> > > >>> > > > > > > > strategy
> > > >>> > > > > > > > > is
> > > >>> > > > > > > > > > > > needed.
> > > >>> > > > > > > > > > >
> > > >>> > > > > > > > > >
> > > >>> > > > > > > > >
> > > >>> > > > > > > >
> > > >>> > > > > > >
> > > >>> > > > > >
> > > >>> > > > >
> > > >>> > > >
> > > >>> > >
> > > >>> >
> > > >>>
> > > >>
> > > >>
> > >
> >
>

Re: branching after GA

[Matt Frantz <ma...@gmail.com>]

RFC here:
https://github.com/apache/incubator-tinkerpop/pull/94


On Fri, Jul 31, 2015 at 3:02 AM, Stephen Mallette <sp...@gmail.com>
wrote:

> Hi David - agreed.  I hadn't done it yet as folks have been on vacation and
> have not had a chance to weigh in on these ideas yet.
>
> On Thu, Jul 30, 2015 at 9:45 PM, David Nalley <da...@gnsa.us> wrote:
>
> > Guys, this thread contains awesome information - can we glean some of
> > it and put it on a web page or wiki page for other new folks so they
> > don't have to complete the question process.
> >
> > On Fri, Jul 24, 2015 at 9:17 AM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> > > It also just occurred to me that the 3.0.1 portion of the CHANGELOG
> needs
> > > to be replicated to the 3.1.0 section as the two may not be the same
> > > (though should be for the most part).
> > >
> > > On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <
> spmallette@gmail.com>
> > > wrote:
> > >
> > >> Yup - I was playing with that.  Let's see if Marko has any thoughts on
> > the
> > >> matter.
> > >>
> > >> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <
> > matthew.h.frantz@gmail.com>
> > >> wrote:
> > >>
> > >>> JIRA has a configurable "Release Notes" report.
> > >>>
> > >>>
> > >>>
> >
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
> > >>>
> > >>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <
> > spmallette@gmail.com>
> > >>> wrote:
> > >>>
> > >>> > I think i like that idea.  It would also force JIRA titles to be
> > written
> > >>> > better though so as to fit the flow of CHANGELOG....sometimes those
> > are
> > >>> > kinda slack.
> > >>> >
> > >>> > On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
> > >>> matthew.h.frantz@gmail.com>
> > >>> > wrote:
> > >>> >
> > >>> > > Correct.  We would make manual additions to the CHANGELOG only to
> > >>> augment
> > >>> > > the JIRA report in some way, either to explain non-JIRA
> activities
> > or
> > >>> to
> > >>> > > draw attention to particular JIRA issues that are significant
> (and
> > we
> > >>> > would
> > >>> > > cite the JIRA ticket from the CHANGELOG for those).  The
> > definition of
> > >>> > > "significant" is discretionary.
> > >>> > >
> > >>> > > On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
> > >>> spmallette@gmail.com
> > >>> > >
> > >>> > > wrote:
> > >>> > >
> > >>> > > > Are you suggesting that on release we rectify the JIRA report
> > with
> > >>> the
> > >>> > > > CHANGELOG?  In that way, if something was done by way of JIRA
> we
> > >>> > wouldn't
> > >>> > > > have to enter a CHANGELOG entry manually, because on release
> we'd
> > >>> pick
> > >>> > it
> > >>> > > > up via the JIRA report?
> > >>> > > >
> > >>> > > > On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
> > >>> > matthew.h.frantz@gmail.com
> > >>> > > >
> > >>> > > > wrote:
> > >>> > > >
> > >>> > > > > Perhaps in the release process we could generate a JIRA
> report
> > of
> > >>> > > issues
> > >>> > > > > marked as fixed in the specific version, and reserve the
> > CHANGELOG
> > >>> > for
> > >>> > > > > significant changes and things that were not tracked through
> > JIRA.
> > >>> > > > >
> > >>> > > > > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
> > >>> > > spmallette@gmail.com>
> > >>> > > > > wrote:
> > >>> > > > >
> > >>> > > > > > We have typically treated CHANGELOG rather
> unscientifically.
> > >>> Make
> > >>> > a
> > >>> > > > > change
> > >>> > > > > > of significance, then update the changelog for the
> > appropriate
> > >>> > > version.
> > >>> > > > > I
> > >>> > > > > > bat around the idea of including the issue ids all the time
> > but
> > >>> > > haven't
> > >>> > > > > > wanted to start the trend of doing that.  Perhaps we do
> that
> > and
> > >>> > make
> > >>> > > > it
> > >>> > > > > > optional?? Not sure how others feel on that matter.
> > >>> > > > > >
> > >>> > > > > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> > >>> > > > > matthew.h.frantz@gmail.com>
> > >>> > > > > > wrote:
> > >>> > > > > >
> > >>> > > > > > > I just merged my fix for TINKERPOP3-782 to both tp30 and
> > >>> > master.  I
> > >>> > > > > > didn't
> > >>> > > > > > > touch CHANGELOG.  Do we do that for every bug fix?  I
> don't
> > >>> see
> > >>> > > > > > references
> > >>> > > > > > > to JIRA artifacts in the CHANGELOG.
> > >>> > > > > > >
> > >>> > > > > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> > >>> > > > > spmallette@gmail.com>
> > >>>
> > >>> > > > > > > wrote:
> > >>> > > > > > >
> > >>> > > > > > > > Hi Matt,
> > >>> > > > > > > >
> > >>> > > > > > > > I have a PR currently targeted at tp30 (because it is a
> > >>> > low-risk
> > >>> > > > bug
> > >>> > > > > > > fix).
> > >>> > > > > > > > > I know that we don't necessarily code review
> everything
> > >>> that
> > >>> > > goes
> > >>> > > > > in,
> > >>> > > > > > > but
> > >>> > > > > > > > > since I'm relatively new, I wouldn't mind someone
> > taking a
> > >>> > peek
> > >>> > > > at
> > >>> > > > > > it,
> > >>> > > > > > > > and
> > >>> > > > > > > > > the verify that tp30 is the best target.
> > >>> > > > > > > > >
> > >>> > > > > > > >
> > >>> > > > > > > > Right - no official code review.  We pretty much tend
> to
> > >>> handle
> > >>> > > it
> > >>> > > > as
> > >>> > > > > > you
> > >>> > > > > > > > just did - on a case-by-case basis.
> > >>> > > > > > > >
> > >>> > > > > > > >
> > >>> > > > > > > > > (I don't have permissions on the GitHub mirror for
> > >>> > > > > > > incubating-tinkerpop.
> > >>> > > > > > > > > Should I?)
> > >>> > > > > > > > >
> > >>> > > > > > > >
> > >>> > > > > > > > I don't think you should - I don't have permissions
> > either.
> > >>> > > > > > > >
> > >>> > > > > > > >
> > >>> > > > > > > > > Also, after it is merged to tp30, is the process
> going
> > to
> > >>> be
> > >>> > > > that I
> > >>> > > > > > > would
> > >>> > > > > > > > > also need to merge tp30 into master?  Or do we plan
> to
> > >>> merge
> > >>> > > only
> > >>> > > > > > > > > occasionally?
> > >>> > > > > > > >
> > >>> > > > > > > >
> > >>> > > > > > > > I've been the only person committing things to tp30 of
> > any
> > >>> > > > substance
> > >>> > > > > so
> > >>> > > > > > > > I've been doing it periodically, but generally
> speaking,
> > I'd
> > >>> > say
> > >>> > > > that
> > >>> > > > > > > it's
> > >>> > > > > > > > best if the person who commits to tp30 merges to master
> > >>> (unless
> > >>> > > > it's
> > >>> > > > > > > > something pretty trivial).  In that way the person who
> > >>> > committed
> > >>> > > to
> > >>> > > > > > tp30
> > >>> > > > > > > is
> > >>> > > > > > > > responsible for ensuring proper integration with
> master.
> > >>> > > > > > > >
> > >>> > > > > > > >
> > >>> > > > > > > >
> > >>> > > > > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> > >>> > > > > > > matthew.h.frantz@gmail.com>
> > >>>
> > >>> > > > > > > > wrote:
> > >>> > > > > > > >
> > >>> > > > > > > > > I have a PR currently targeted at tp30 (because it
> is a
> > >>> > > low-risk
> > >>> > > > > bug
> > >>> > > > > > > > fix).
> > >>> > > > > > > > > I know that we don't necessarily code review
> everything
> > >>> that
> > >>> > > goes
> > >>> > > > > in,
> > >>> > > > > > > but
> > >>> > > > > > > > > since I'm relatively new, I wouldn't mind someone
> > taking a
> > >>> > peek
> > >>> > > > at
> > >>> > > > > > it,
> > >>> > > > > > > > and
> > >>> > > > > > > > > the verify that tp30 is the best target.
> > >>> > > > > > > > >
> > >>> > > > > > > > > (I don't have permissions on the GitHub mirror for
> > >>> > > > > > > incubating-tinkerpop.
> > >>> > > > > > > > > Should I?)
> > >>> > > > > > > > >
> > >>> > > > > > > > > Also, after it is merged to tp30, is the process
> going
> > to
> > >>> be
> > >>> > > > that I
> > >>> > > > > > > would
> > >>> > > > > > > > > also need to merge tp30 into master?  Or do we plan
> to
> > >>> merge
> > >>> > > only
> > >>> > > > > > > > > occasionally?
> > >>> > > > > > > > >
> > >>> > > > > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> > >>> > > > > > > spmallette@gmail.com>
> > >>>
> > >>> > > > > > > > > wrote:
> > >>> > > > > > > > >
> > >>> > > > > > > > > > Thanks JB - i'm familiar with semver and I think
> the
> > >>> idea
> > >>> > is
> > >>> > > to
> > >>> > > > > > > follow
> > >>> > > > > > > > it
> > >>> > > > > > > > > > in principle, in that we will save API breaking
> > change
> > >>> for
> > >>> > > the
> > >>> > > > > > > "minor"
> > >>> > > > > > > > > > version.   imo, we should stick to the three digit
> > >>> system
> > >>> > for
> > >>> > > > now
> > >>> > > > > > > but I
> > >>> > > > > > > > > > guess it's worth considering what a "breaking
> change"
> > >>> is in
> > >>> > > our
> > >>> > > > > > > > context.
> > >>> > > > > > > > > >
> > >>> > > > > > > > > > TinkerPop is "big" - it has both public and
> internal
> > >>> APIs.
> > >>> > > if
> > >>> > > > i
> > >>> > > > > > > change
> > >>> > > > > > > > > the
> > >>> > > > > > > > > > package name of an internal API in a patch
> release, I
> > >>> > > wouldn't
> > >>> > > > > > expect
> > >>> > > > > > > > > that
> > >>> > > > > > > > > > to break anyone and thus I'm not sure I'd consider
> > that
> > >>> a
> > >>> > > > > breaking
> > >>> > > > > > > > change
> > >>> > > > > > > > > >  (though it's always interesting to see how folks
> > find
> > >>> > their
> > >>> > > > way
> > >>> > > > > > into
> > >>> > > > > > > > > using
> > >>> > > > > > > > > > our internal classes) .  To me the "breaking
> changes"
> > >>> are
> > >>> > > ones
> > >>> > > > > that
> > >>> > > > > > > > occur
> > >>> > > > > > > > > > in the public classes (i.e. the ones people are
> > likely
> > >>> to
> > >>> > > use)
> > >>> > > > > > like:
> > >>> > > > > > > > > > gremlin driver classes, structure API for vendors,
> > step
> > >>> > > classes
> > >>> > > > > and
> > >>> > > > > > > > > > GraphTraversal/GraphTraversalSource, etc. Changing
> > those
> > >>> > > > classes
> > >>> > > > > in
> > >>> > > > > > > > some
> > >>> > > > > > > > > > way, would break the greatest percentage of users.
> > I'm
> > >>> not
> > >>> > > > sure
> > >>> > > > > > how
> > >>> > > > > > > > > others
> > >>> > > > > > > > > > feel, but I tend to think of "breaking change" in
> > that
> > >>> more
> > >>> > > > fuzzy
> > >>> > > > > > > > > fashion.
> > >>> > > > > > > > > >
> > >>> > > > > > > > > >
> > >>> > > > > > > > > >
> > >>> > > > > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste
> Musso
> > <
> > >>> > > > > > > > jbmusso@gmail.com>
> > >>>
> > >>> > > > > > > > > > wrote:
> > >>> > > > > > > > > >
> > >>> > > > > > > > > > > Related - have you considered using semantic
> > >>> versioning
> > >>> > [1]
> > >>> > > > > > > > > > > (major.minor.patch)? Roughly, semver states that
> > >>> breaking
> > >>> > > > > changes
> > >>> > > > > > > > > > > should bump major, new backward-compatible
> features
> > >>> > should
> > >>> > > > bump
> > >>> > > > > > > minor
> > >>> > > > > > > > > > > while bug fixes should bump patch. It also
> supports
> > >>> > > > pre-release
> > >>> > > > > > > > > > > version (-alpha, -incubating or -whatever
> > suffixes).
> > >>> > > > > > > > > > >
> > >>> > > > > > > > > > > In order to avoid having the first digit (major)
> > being
> > >>> > > bumped
> > >>> > > > > too
> > >>> > > > > > > > > > > often (TP3 shall remain TP3!), a variation could
> > be:
> > >>> > > > > > > > > > > marketing.major.minor.patch (downside to that is
> 4
> > >>> digits
> > >>> > > > > > > versioning
> > >>> > > > > > > > > > > instead of 3). For example, adding a new Gremlin
> > step
> > >>> > would
> > >>> > > > > bump
> > >>> > > > > > > > minor
> > >>> > > > > > > > > > > while changing a step signature in a
> > >>> > backward-incompatible
> > >>> > > > > manner
> > >>> > > > > > > > > > > would bump major.
> > >>> > > > > > > > > > >
> > >>> > > > > > > > > > > semver is very popular in the JavaScript/Node.js
> > world
> > >>> > and
> > >>> > > > used
> > >>> > > > > > > > > > > extensively with npm (node package manager).
> > >>> > > > > > > > > > >
> > >>> > > > > > > > > > > Just some thoughts.
> > >>> > > > > > > > > > >
> > >>> > > > > > > > > > > Jean-Baptiste
> > >>> > > > > > > > > > >
> > >>> > > > > > > > > > > [1] http://semver.org/
> > >>> > > > > > > > > > >
> > >>> > > > > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen
> Mallette <
> > >>> > > > > > > > > spmallette@gmail.com>
> > >>>
> > >>> > > > > > > > > > > wrote:
> > >>> > > > > > > > > > > > I think it's worthwhile for us to do something
> > we've
> > >>> > not
> > >>> > > > > really
> > >>> > > > > > > > done
> > >>> > > > > > > > > > > before
> > >>> > > > > > > > > > > > with any of the TinkerPop projects: use
> > branches. We
> > >>> > > > > typically
> > >>> > > > > > > tend
> > >>> > > > > > > > > to
> > >>> > > > > > > > > > > use
> > >>> > > > > > > > > > > > branches for major refactoring that we might
> > throw
> > >>> out,
> > >>> > > but
> > >>> > > > > not
> > >>> > > > > > > > > really
> > >>> > > > > > > > > > > for
> > >>> > > > > > > > > > > > release management. As we look past release
> > 3.0.0, I
> > >>> > > think
> > >>> > > > we
> > >>> > > > > > > will
> > >>> > > > > > > > > want
> > >>> > > > > > > > > > > to
> > >>> > > > > > > > > > > > have the capability to do more frequent minor
> > >>> releases
> > >>> > > > (e.g.
> > >>> > > > > > > 3.0.1,
> > >>> > > > > > > > > > > 3.0.2,
> > >>> > > > > > > > > > > > etc) while still being able to do work for a
> > future
> > >>> > 3.1.x
> > >>> > > > > line
> > >>> > > > > > of
> > >>> > > > > > > > > code.
> > >>> > > > > > > > > > > >
> > >>> > > > > > > > > > > > I think we can do this without too much change
> > if we
> > >>> > > > > introduce
> > >>> > > > > > a
> > >>> > > > > > > > > simple
> > >>> > > > > > > > > > > > branch system.  Release branch rules would be
> > >>> simple -
> > >>> > we
> > >>> > > > > > create
> > >>> > > > > > > a
> > >>> > > > > > > > > new
> > >>> > > > > > > > > > > > branch from master called tp31 for the 3.1.x
> > line of
> > >>> > > code.
> > >>> > > > > Any
> > >>> > > > > > > > > changes
> > >>> > > > > > > > > > > > that are "breaking", introduce significant
> risk,
> > a
> > >>> > > "major"
> > >>> > > > > > > feature,
> > >>> > > > > > > > > > etc.
> > >>> > > > > > > > > > > > would be committed there.  All other changes,
> bug
> > >>> > fixes,
> > >>> > > > > > > > non-breaking
> > >>> > > > > > > > > > > > refactoring of major APIs, "minor" features,
> etc.
> > >>> would
> > >>> > > > > simply
> > >>> > > > > > > > commit
> > >>> > > > > > > > > > to
> > >>> > > > > > > > > > > > master.  the master branch effectively becomes
> > the
> > >>> > 3.0.x
> > >>> > > > line
> > >>> > > > > > of
> > >>> > > > > > > > > code.
> > >>> > > > > > > > > > > > Under this approach the merge process is pretty
> > >>> simple
> > >>> > in
> > >>> > > > > that
> > >>> > > > > > we
> > >>> > > > > > > > > just
> > >>> > > > > > > > > > > > merge forward (i.e. master merges to to tp31).
> > >>> > > > > > > > > > > >
> > >>> > > > > > > > > > > > When the day comes that we're ready to release
> > >>> 3.1.0,
> > >>> > we
> > >>> > > > > merge
> > >>> > > > > > > tp31
> > >>> > > > > > > > > > back
> > >>> > > > > > > > > > > to
> > >>> > > > > > > > > > > > master and create tp32 and use the same model
> > where
> > >>> the
> > >>> > > > 3.1.x
> > >>> > > > > > > line
> > >>> > > > > > > > is
> > >>> > > > > > > > > > > > master and the 3.2.x line is tp32.  Of course,
> > under
> > >>> > this
> > >>> > > > > model
> > >>> > > > > > > we
> > >>> > > > > > > > > are
> > >>> > > > > > > > > > > > really supporting just the previous minor
> > version,
> > >>> > which
> > >>> > > > for
> > >>> > > > > > > right
> > >>> > > > > > > > > now
> > >>> > > > > > > > > > > > seems acceptable to me.  That's more than what
> > we've
> > >>> > ever
> > >>> > > > > > really
> > >>> > > > > > > > done
> > >>> > > > > > > > > > > well,
> > >>> > > > > > > > > > > > so that feels like a good starting point in my
> > book.
> > >>> > > After
> > >>> > > > > we
> > >>> > > > > > > > > release
> > >>> > > > > > > > > > > > 3.1.0 we can revisit and decide if a more
> complex
> > >>> > > branching
> > >>> > > > > > > > strategy
> > >>> > > > > > > > > is
> > >>> > > > > > > > > > > > needed.
> > >>> > > > > > > > > > >
> > >>> > > > > > > > > >
> > >>> > > > > > > > >
> > >>> > > > > > > >
> > >>> > > > > > >
> > >>> > > > > >
> > >>> > > > >
> > >>> > > >
> > >>> > >
> > >>> >
> > >>>
> > >>
> > >>
> >
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

Hi David - agreed.  I hadn't done it yet as folks have been on vacation and
have not had a chance to weigh in on these ideas yet.

On Thu, Jul 30, 2015 at 9:45 PM, David Nalley <da...@gnsa.us> wrote:

> Guys, this thread contains awesome information - can we glean some of
> it and put it on a web page or wiki page for other new folks so they
> don't have to complete the question process.
>
> On Fri, Jul 24, 2015 at 9:17 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
> > It also just occurred to me that the 3.0.1 portion of the CHANGELOG needs
> > to be replicated to the 3.1.0 section as the two may not be the same
> > (though should be for the most part).
> >
> > On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> >
> >> Yup - I was playing with that.  Let's see if Marko has any thoughts on
> the
> >> matter.
> >>
> >> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <
> matthew.h.frantz@gmail.com>
> >> wrote:
> >>
> >>> JIRA has a configurable "Release Notes" report.
> >>>
> >>>
> >>>
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
> >>>
> >>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <
> spmallette@gmail.com>
> >>> wrote:
> >>>
> >>> > I think i like that idea.  It would also force JIRA titles to be
> written
> >>> > better though so as to fit the flow of CHANGELOG....sometimes those
> are
> >>> > kinda slack.
> >>> >
> >>> > On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
> >>> matthew.h.frantz@gmail.com>
> >>> > wrote:
> >>> >
> >>> > > Correct.  We would make manual additions to the CHANGELOG only to
> >>> augment
> >>> > > the JIRA report in some way, either to explain non-JIRA activities
> or
> >>> to
> >>> > > draw attention to particular JIRA issues that are significant (and
> we
> >>> > would
> >>> > > cite the JIRA ticket from the CHANGELOG for those).  The
> definition of
> >>> > > "significant" is discretionary.
> >>> > >
> >>> > > On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
> >>> spmallette@gmail.com
> >>> > >
> >>> > > wrote:
> >>> > >
> >>> > > > Are you suggesting that on release we rectify the JIRA report
> with
> >>> the
> >>> > > > CHANGELOG?  In that way, if something was done by way of JIRA we
> >>> > wouldn't
> >>> > > > have to enter a CHANGELOG entry manually, because on release we'd
> >>> pick
> >>> > it
> >>> > > > up via the JIRA report?
> >>> > > >
> >>> > > > On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
> >>> > matthew.h.frantz@gmail.com
> >>> > > >
> >>> > > > wrote:
> >>> > > >
> >>> > > > > Perhaps in the release process we could generate a JIRA report
> of
> >>> > > issues
> >>> > > > > marked as fixed in the specific version, and reserve the
> CHANGELOG
> >>> > for
> >>> > > > > significant changes and things that were not tracked through
> JIRA.
> >>> > > > >
> >>> > > > > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
> >>> > > spmallette@gmail.com>
> >>> > > > > wrote:
> >>> > > > >
> >>> > > > > > We have typically treated CHANGELOG rather unscientifically.
> >>> Make
> >>> > a
> >>> > > > > change
> >>> > > > > > of significance, then update the changelog for the
> appropriate
> >>> > > version.
> >>> > > > > I
> >>> > > > > > bat around the idea of including the issue ids all the time
> but
> >>> > > haven't
> >>> > > > > > wanted to start the trend of doing that.  Perhaps we do that
> and
> >>> > make
> >>> > > > it
> >>> > > > > > optional?? Not sure how others feel on that matter.
> >>> > > > > >
> >>> > > > > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> >>> > > > > matthew.h.frantz@gmail.com>
> >>> > > > > > wrote:
> >>> > > > > >
> >>> > > > > > > I just merged my fix for TINKERPOP3-782 to both tp30 and
> >>> > master.  I
> >>> > > > > > didn't
> >>> > > > > > > touch CHANGELOG.  Do we do that for every bug fix?  I don't
> >>> see
> >>> > > > > > references
> >>> > > > > > > to JIRA artifacts in the CHANGELOG.
> >>> > > > > > >
> >>> > > > > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> >>> > > > > spmallette@gmail.com>
> >>>
> >>> > > > > > > wrote:
> >>> > > > > > >
> >>> > > > > > > > Hi Matt,
> >>> > > > > > > >
> >>> > > > > > > > I have a PR currently targeted at tp30 (because it is a
> >>> > low-risk
> >>> > > > bug
> >>> > > > > > > fix).
> >>> > > > > > > > > I know that we don't necessarily code review everything
> >>> that
> >>> > > goes
> >>> > > > > in,
> >>> > > > > > > but
> >>> > > > > > > > > since I'm relatively new, I wouldn't mind someone
> taking a
> >>> > peek
> >>> > > > at
> >>> > > > > > it,
> >>> > > > > > > > and
> >>> > > > > > > > > the verify that tp30 is the best target.
> >>> > > > > > > > >
> >>> > > > > > > >
> >>> > > > > > > > Right - no official code review.  We pretty much tend to
> >>> handle
> >>> > > it
> >>> > > > as
> >>> > > > > > you
> >>> > > > > > > > just did - on a case-by-case basis.
> >>> > > > > > > >
> >>> > > > > > > >
> >>> > > > > > > > > (I don't have permissions on the GitHub mirror for
> >>> > > > > > > incubating-tinkerpop.
> >>> > > > > > > > > Should I?)
> >>> > > > > > > > >
> >>> > > > > > > >
> >>> > > > > > > > I don't think you should - I don't have permissions
> either.
> >>> > > > > > > >
> >>> > > > > > > >
> >>> > > > > > > > > Also, after it is merged to tp30, is the process going
> to
> >>> be
> >>> > > > that I
> >>> > > > > > > would
> >>> > > > > > > > > also need to merge tp30 into master?  Or do we plan to
> >>> merge
> >>> > > only
> >>> > > > > > > > > occasionally?
> >>> > > > > > > >
> >>> > > > > > > >
> >>> > > > > > > > I've been the only person committing things to tp30 of
> any
> >>> > > > substance
> >>> > > > > so
> >>> > > > > > > > I've been doing it periodically, but generally speaking,
> I'd
> >>> > say
> >>> > > > that
> >>> > > > > > > it's
> >>> > > > > > > > best if the person who commits to tp30 merges to master
> >>> (unless
> >>> > > > it's
> >>> > > > > > > > something pretty trivial).  In that way the person who
> >>> > committed
> >>> > > to
> >>> > > > > > tp30
> >>> > > > > > > is
> >>> > > > > > > > responsible for ensuring proper integration with master.
> >>> > > > > > > >
> >>> > > > > > > >
> >>> > > > > > > >
> >>> > > > > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> >>> > > > > > > matthew.h.frantz@gmail.com>
> >>>
> >>> > > > > > > > wrote:
> >>> > > > > > > >
> >>> > > > > > > > > I have a PR currently targeted at tp30 (because it is a
> >>> > > low-risk
> >>> > > > > bug
> >>> > > > > > > > fix).
> >>> > > > > > > > > I know that we don't necessarily code review everything
> >>> that
> >>> > > goes
> >>> > > > > in,
> >>> > > > > > > but
> >>> > > > > > > > > since I'm relatively new, I wouldn't mind someone
> taking a
> >>> > peek
> >>> > > > at
> >>> > > > > > it,
> >>> > > > > > > > and
> >>> > > > > > > > > the verify that tp30 is the best target.
> >>> > > > > > > > >
> >>> > > > > > > > > (I don't have permissions on the GitHub mirror for
> >>> > > > > > > incubating-tinkerpop.
> >>> > > > > > > > > Should I?)
> >>> > > > > > > > >
> >>> > > > > > > > > Also, after it is merged to tp30, is the process going
> to
> >>> be
> >>> > > > that I
> >>> > > > > > > would
> >>> > > > > > > > > also need to merge tp30 into master?  Or do we plan to
> >>> merge
> >>> > > only
> >>> > > > > > > > > occasionally?
> >>> > > > > > > > >
> >>> > > > > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> >>> > > > > > > spmallette@gmail.com>
> >>>
> >>> > > > > > > > > wrote:
> >>> > > > > > > > >
> >>> > > > > > > > > > Thanks JB - i'm familiar with semver and I think the
> >>> idea
> >>> > is
> >>> > > to
> >>> > > > > > > follow
> >>> > > > > > > > it
> >>> > > > > > > > > > in principle, in that we will save API breaking
> change
> >>> for
> >>> > > the
> >>> > > > > > > "minor"
> >>> > > > > > > > > > version.   imo, we should stick to the three digit
> >>> system
> >>> > for
> >>> > > > now
> >>> > > > > > > but I
> >>> > > > > > > > > > guess it's worth considering what a "breaking change"
> >>> is in
> >>> > > our
> >>> > > > > > > > context.
> >>> > > > > > > > > >
> >>> > > > > > > > > > TinkerPop is "big" - it has both public and internal
> >>> APIs.
> >>> > > if
> >>> > > > i
> >>> > > > > > > change
> >>> > > > > > > > > the
> >>> > > > > > > > > > package name of an internal API in a patch release, I
> >>> > > wouldn't
> >>> > > > > > expect
> >>> > > > > > > > > that
> >>> > > > > > > > > > to break anyone and thus I'm not sure I'd consider
> that
> >>> a
> >>> > > > > breaking
> >>> > > > > > > > change
> >>> > > > > > > > > >  (though it's always interesting to see how folks
> find
> >>> > their
> >>> > > > way
> >>> > > > > > into
> >>> > > > > > > > > using
> >>> > > > > > > > > > our internal classes) .  To me the "breaking changes"
> >>> are
> >>> > > ones
> >>> > > > > that
> >>> > > > > > > > occur
> >>> > > > > > > > > > in the public classes (i.e. the ones people are
> likely
> >>> to
> >>> > > use)
> >>> > > > > > like:
> >>> > > > > > > > > > gremlin driver classes, structure API for vendors,
> step
> >>> > > classes
> >>> > > > > and
> >>> > > > > > > > > > GraphTraversal/GraphTraversalSource, etc. Changing
> those
> >>> > > > classes
> >>> > > > > in
> >>> > > > > > > > some
> >>> > > > > > > > > > way, would break the greatest percentage of users.
> I'm
> >>> not
> >>> > > > sure
> >>> > > > > > how
> >>> > > > > > > > > others
> >>> > > > > > > > > > feel, but I tend to think of "breaking change" in
> that
> >>> more
> >>> > > > fuzzy
> >>> > > > > > > > > fashion.
> >>> > > > > > > > > >
> >>> > > > > > > > > >
> >>> > > > > > > > > >
> >>> > > > > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso
> <
> >>> > > > > > > > jbmusso@gmail.com>
> >>>
> >>> > > > > > > > > > wrote:
> >>> > > > > > > > > >
> >>> > > > > > > > > > > Related - have you considered using semantic
> >>> versioning
> >>> > [1]
> >>> > > > > > > > > > > (major.minor.patch)? Roughly, semver states that
> >>> breaking
> >>> > > > > changes
> >>> > > > > > > > > > > should bump major, new backward-compatible features
> >>> > should
> >>> > > > bump
> >>> > > > > > > minor
> >>> > > > > > > > > > > while bug fixes should bump patch. It also supports
> >>> > > > pre-release
> >>> > > > > > > > > > > version (-alpha, -incubating or -whatever
> suffixes).
> >>> > > > > > > > > > >
> >>> > > > > > > > > > > In order to avoid having the first digit (major)
> being
> >>> > > bumped
> >>> > > > > too
> >>> > > > > > > > > > > often (TP3 shall remain TP3!), a variation could
> be:
> >>> > > > > > > > > > > marketing.major.minor.patch (downside to that is 4
> >>> digits
> >>> > > > > > > versioning
> >>> > > > > > > > > > > instead of 3). For example, adding a new Gremlin
> step
> >>> > would
> >>> > > > > bump
> >>> > > > > > > > minor
> >>> > > > > > > > > > > while changing a step signature in a
> >>> > backward-incompatible
> >>> > > > > manner
> >>> > > > > > > > > > > would bump major.
> >>> > > > > > > > > > >
> >>> > > > > > > > > > > semver is very popular in the JavaScript/Node.js
> world
> >>> > and
> >>> > > > used
> >>> > > > > > > > > > > extensively with npm (node package manager).
> >>> > > > > > > > > > >
> >>> > > > > > > > > > > Just some thoughts.
> >>> > > > > > > > > > >
> >>> > > > > > > > > > > Jean-Baptiste
> >>> > > > > > > > > > >
> >>> > > > > > > > > > > [1] http://semver.org/
> >>> > > > > > > > > > >
> >>> > > > > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> >>> > > > > > > > > spmallette@gmail.com>
> >>>
> >>> > > > > > > > > > > wrote:
> >>> > > > > > > > > > > > I think it's worthwhile for us to do something
> we've
> >>> > not
> >>> > > > > really
> >>> > > > > > > > done
> >>> > > > > > > > > > > before
> >>> > > > > > > > > > > > with any of the TinkerPop projects: use
> branches. We
> >>> > > > > typically
> >>> > > > > > > tend
> >>> > > > > > > > > to
> >>> > > > > > > > > > > use
> >>> > > > > > > > > > > > branches for major refactoring that we might
> throw
> >>> out,
> >>> > > but
> >>> > > > > not
> >>> > > > > > > > > really
> >>> > > > > > > > > > > for
> >>> > > > > > > > > > > > release management. As we look past release
> 3.0.0, I
> >>> > > think
> >>> > > > we
> >>> > > > > > > will
> >>> > > > > > > > > want
> >>> > > > > > > > > > > to
> >>> > > > > > > > > > > > have the capability to do more frequent minor
> >>> releases
> >>> > > > (e.g.
> >>> > > > > > > 3.0.1,
> >>> > > > > > > > > > > 3.0.2,
> >>> > > > > > > > > > > > etc) while still being able to do work for a
> future
> >>> > 3.1.x
> >>> > > > > line
> >>> > > > > > of
> >>> > > > > > > > > code.
> >>> > > > > > > > > > > >
> >>> > > > > > > > > > > > I think we can do this without too much change
> if we
> >>> > > > > introduce
> >>> > > > > > a
> >>> > > > > > > > > simple
> >>> > > > > > > > > > > > branch system.  Release branch rules would be
> >>> simple -
> >>> > we
> >>> > > > > > create
> >>> > > > > > > a
> >>> > > > > > > > > new
> >>> > > > > > > > > > > > branch from master called tp31 for the 3.1.x
> line of
> >>> > > code.
> >>> > > > > Any
> >>> > > > > > > > > changes
> >>> > > > > > > > > > > > that are "breaking", introduce significant risk,
> a
> >>> > > "major"
> >>> > > > > > > feature,
> >>> > > > > > > > > > etc.
> >>> > > > > > > > > > > > would be committed there.  All other changes, bug
> >>> > fixes,
> >>> > > > > > > > non-breaking
> >>> > > > > > > > > > > > refactoring of major APIs, "minor" features, etc.
> >>> would
> >>> > > > > simply
> >>> > > > > > > > commit
> >>> > > > > > > > > > to
> >>> > > > > > > > > > > > master.  the master branch effectively becomes
> the
> >>> > 3.0.x
> >>> > > > line
> >>> > > > > > of
> >>> > > > > > > > > code.
> >>> > > > > > > > > > > > Under this approach the merge process is pretty
> >>> simple
> >>> > in
> >>> > > > > that
> >>> > > > > > we
> >>> > > > > > > > > just
> >>> > > > > > > > > > > > merge forward (i.e. master merges to to tp31).
> >>> > > > > > > > > > > >
> >>> > > > > > > > > > > > When the day comes that we're ready to release
> >>> 3.1.0,
> >>> > we
> >>> > > > > merge
> >>> > > > > > > tp31
> >>> > > > > > > > > > back
> >>> > > > > > > > > > > to
> >>> > > > > > > > > > > > master and create tp32 and use the same model
> where
> >>> the
> >>> > > > 3.1.x
> >>> > > > > > > line
> >>> > > > > > > > is
> >>> > > > > > > > > > > > master and the 3.2.x line is tp32.  Of course,
> under
> >>> > this
> >>> > > > > model
> >>> > > > > > > we
> >>> > > > > > > > > are
> >>> > > > > > > > > > > > really supporting just the previous minor
> version,
> >>> > which
> >>> > > > for
> >>> > > > > > > right
> >>> > > > > > > > > now
> >>> > > > > > > > > > > > seems acceptable to me.  That's more than what
> we've
> >>> > ever
> >>> > > > > > really
> >>> > > > > > > > done
> >>> > > > > > > > > > > well,
> >>> > > > > > > > > > > > so that feels like a good starting point in my
> book.
> >>> > > After
> >>> > > > > we
> >>> > > > > > > > > release
> >>> > > > > > > > > > > > 3.1.0 we can revisit and decide if a more complex
> >>> > > branching
> >>> > > > > > > > strategy
> >>> > > > > > > > > is
> >>> > > > > > > > > > > > needed.
> >>> > > > > > > > > > >
> >>> > > > > > > > > >
> >>> > > > > > > > >
> >>> > > > > > > >
> >>> > > > > > >
> >>> > > > > >
> >>> > > > >
> >>> > > >
> >>> > >
> >>> >
> >>>
> >>
> >>
>

Re: branching after GA

[David Nalley <da...@gnsa.us>]

Guys, this thread contains awesome information - can we glean some of
it and put it on a web page or wiki page for other new folks so they
don't have to complete the question process.

On Fri, Jul 24, 2015 at 9:17 AM, Stephen Mallette <sp...@gmail.com> wrote:
> It also just occurred to me that the 3.0.1 portion of the CHANGELOG needs
> to be replicated to the 3.1.0 section as the two may not be the same
> (though should be for the most part).
>
> On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
>> Yup - I was playing with that.  Let's see if Marko has any thoughts on the
>> matter.
>>
>> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <ma...@gmail.com>
>> wrote:
>>
>>> JIRA has a configurable "Release Notes" report.
>>>
>>>
>>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
>>>
>>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <sp...@gmail.com>
>>> wrote:
>>>
>>> > I think i like that idea.  It would also force JIRA titles to be written
>>> > better though so as to fit the flow of CHANGELOG....sometimes those are
>>> > kinda slack.
>>> >
>>> > On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
>>> matthew.h.frantz@gmail.com>
>>> > wrote:
>>> >
>>> > > Correct.  We would make manual additions to the CHANGELOG only to
>>> augment
>>> > > the JIRA report in some way, either to explain non-JIRA activities or
>>> to
>>> > > draw attention to particular JIRA issues that are significant (and we
>>> > would
>>> > > cite the JIRA ticket from the CHANGELOG for those).  The definition of
>>> > > "significant" is discretionary.
>>> > >
>>> > > On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
>>> spmallette@gmail.com
>>> > >
>>> > > wrote:
>>> > >
>>> > > > Are you suggesting that on release we rectify the JIRA report with
>>> the
>>> > > > CHANGELOG?  In that way, if something was done by way of JIRA we
>>> > wouldn't
>>> > > > have to enter a CHANGELOG entry manually, because on release we'd
>>> pick
>>> > it
>>> > > > up via the JIRA report?
>>> > > >
>>> > > > On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
>>> > matthew.h.frantz@gmail.com
>>> > > >
>>> > > > wrote:
>>> > > >
>>> > > > > Perhaps in the release process we could generate a JIRA report of
>>> > > issues
>>> > > > > marked as fixed in the specific version, and reserve the CHANGELOG
>>> > for
>>> > > > > significant changes and things that were not tracked through JIRA.
>>> > > > >
>>> > > > > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
>>> > > spmallette@gmail.com>
>>> > > > > wrote:
>>> > > > >
>>> > > > > > We have typically treated CHANGELOG rather unscientifically.
>>> Make
>>> > a
>>> > > > > change
>>> > > > > > of significance, then update the changelog for the appropriate
>>> > > version.
>>> > > > > I
>>> > > > > > bat around the idea of including the issue ids all the time but
>>> > > haven't
>>> > > > > > wanted to start the trend of doing that.  Perhaps we do that and
>>> > make
>>> > > > it
>>> > > > > > optional?? Not sure how others feel on that matter.
>>> > > > > >
>>> > > > > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
>>> > > > > matthew.h.frantz@gmail.com>
>>> > > > > > wrote:
>>> > > > > >
>>> > > > > > > I just merged my fix for TINKERPOP3-782 to both tp30 and
>>> > master.  I
>>> > > > > > didn't
>>> > > > > > > touch CHANGELOG.  Do we do that for every bug fix?  I don't
>>> see
>>> > > > > > references
>>> > > > > > > to JIRA artifacts in the CHANGELOG.
>>> > > > > > >
>>> > > > > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
>>> > > > > spmallette@gmail.com>
>>>
>>> > > > > > > wrote:
>>> > > > > > >
>>> > > > > > > > Hi Matt,
>>> > > > > > > >
>>> > > > > > > > I have a PR currently targeted at tp30 (because it is a
>>> > low-risk
>>> > > > bug
>>> > > > > > > fix).
>>> > > > > > > > > I know that we don't necessarily code review everything
>>> that
>>> > > goes
>>> > > > > in,
>>> > > > > > > but
>>> > > > > > > > > since I'm relatively new, I wouldn't mind someone taking a
>>> > peek
>>> > > > at
>>> > > > > > it,
>>> > > > > > > > and
>>> > > > > > > > > the verify that tp30 is the best target.
>>> > > > > > > > >
>>> > > > > > > >
>>> > > > > > > > Right - no official code review.  We pretty much tend to
>>> handle
>>> > > it
>>> > > > as
>>> > > > > > you
>>> > > > > > > > just did - on a case-by-case basis.
>>> > > > > > > >
>>> > > > > > > >
>>> > > > > > > > > (I don't have permissions on the GitHub mirror for
>>> > > > > > > incubating-tinkerpop.
>>> > > > > > > > > Should I?)
>>> > > > > > > > >
>>> > > > > > > >
>>> > > > > > > > I don't think you should - I don't have permissions either.
>>> > > > > > > >
>>> > > > > > > >
>>> > > > > > > > > Also, after it is merged to tp30, is the process going to
>>> be
>>> > > > that I
>>> > > > > > > would
>>> > > > > > > > > also need to merge tp30 into master?  Or do we plan to
>>> merge
>>> > > only
>>> > > > > > > > > occasionally?
>>> > > > > > > >
>>> > > > > > > >
>>> > > > > > > > I've been the only person committing things to tp30 of any
>>> > > > substance
>>> > > > > so
>>> > > > > > > > I've been doing it periodically, but generally speaking, I'd
>>> > say
>>> > > > that
>>> > > > > > > it's
>>> > > > > > > > best if the person who commits to tp30 merges to master
>>> (unless
>>> > > > it's
>>> > > > > > > > something pretty trivial).  In that way the person who
>>> > committed
>>> > > to
>>> > > > > > tp30
>>> > > > > > > is
>>> > > > > > > > responsible for ensuring proper integration with master.
>>> > > > > > > >
>>> > > > > > > >
>>> > > > > > > >
>>> > > > > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
>>> > > > > > > matthew.h.frantz@gmail.com>
>>>
>>> > > > > > > > wrote:
>>> > > > > > > >
>>> > > > > > > > > I have a PR currently targeted at tp30 (because it is a
>>> > > low-risk
>>> > > > > bug
>>> > > > > > > > fix).
>>> > > > > > > > > I know that we don't necessarily code review everything
>>> that
>>> > > goes
>>> > > > > in,
>>> > > > > > > but
>>> > > > > > > > > since I'm relatively new, I wouldn't mind someone taking a
>>> > peek
>>> > > > at
>>> > > > > > it,
>>> > > > > > > > and
>>> > > > > > > > > the verify that tp30 is the best target.
>>> > > > > > > > >
>>> > > > > > > > > (I don't have permissions on the GitHub mirror for
>>> > > > > > > incubating-tinkerpop.
>>> > > > > > > > > Should I?)
>>> > > > > > > > >
>>> > > > > > > > > Also, after it is merged to tp30, is the process going to
>>> be
>>> > > > that I
>>> > > > > > > would
>>> > > > > > > > > also need to merge tp30 into master?  Or do we plan to
>>> merge
>>> > > only
>>> > > > > > > > > occasionally?
>>> > > > > > > > >
>>> > > > > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
>>> > > > > > > spmallette@gmail.com>
>>>
>>> > > > > > > > > wrote:
>>> > > > > > > > >
>>> > > > > > > > > > Thanks JB - i'm familiar with semver and I think the
>>> idea
>>> > is
>>> > > to
>>> > > > > > > follow
>>> > > > > > > > it
>>> > > > > > > > > > in principle, in that we will save API breaking change
>>> for
>>> > > the
>>> > > > > > > "minor"
>>> > > > > > > > > > version.   imo, we should stick to the three digit
>>> system
>>> > for
>>> > > > now
>>> > > > > > > but I
>>> > > > > > > > > > guess it's worth considering what a "breaking change"
>>> is in
>>> > > our
>>> > > > > > > > context.
>>> > > > > > > > > >
>>> > > > > > > > > > TinkerPop is "big" - it has both public and internal
>>> APIs.
>>> > > if
>>> > > > i
>>> > > > > > > change
>>> > > > > > > > > the
>>> > > > > > > > > > package name of an internal API in a patch release, I
>>> > > wouldn't
>>> > > > > > expect
>>> > > > > > > > > that
>>> > > > > > > > > > to break anyone and thus I'm not sure I'd consider that
>>> a
>>> > > > > breaking
>>> > > > > > > > change
>>> > > > > > > > > >  (though it's always interesting to see how folks find
>>> > their
>>> > > > way
>>> > > > > > into
>>> > > > > > > > > using
>>> > > > > > > > > > our internal classes) .  To me the "breaking changes"
>>> are
>>> > > ones
>>> > > > > that
>>> > > > > > > > occur
>>> > > > > > > > > > in the public classes (i.e. the ones people are likely
>>> to
>>> > > use)
>>> > > > > > like:
>>> > > > > > > > > > gremlin driver classes, structure API for vendors, step
>>> > > classes
>>> > > > > and
>>> > > > > > > > > > GraphTraversal/GraphTraversalSource, etc. Changing those
>>> > > > classes
>>> > > > > in
>>> > > > > > > > some
>>> > > > > > > > > > way, would break the greatest percentage of users.  I'm
>>> not
>>> > > > sure
>>> > > > > > how
>>> > > > > > > > > others
>>> > > > > > > > > > feel, but I tend to think of "breaking change" in that
>>> more
>>> > > > fuzzy
>>> > > > > > > > > fashion.
>>> > > > > > > > > >
>>> > > > > > > > > >
>>> > > > > > > > > >
>>> > > > > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
>>> > > > > > > > jbmusso@gmail.com>
>>>
>>> > > > > > > > > > wrote:
>>> > > > > > > > > >
>>> > > > > > > > > > > Related - have you considered using semantic
>>> versioning
>>> > [1]
>>> > > > > > > > > > > (major.minor.patch)? Roughly, semver states that
>>> breaking
>>> > > > > changes
>>> > > > > > > > > > > should bump major, new backward-compatible features
>>> > should
>>> > > > bump
>>> > > > > > > minor
>>> > > > > > > > > > > while bug fixes should bump patch. It also supports
>>> > > > pre-release
>>> > > > > > > > > > > version (-alpha, -incubating or -whatever suffixes).
>>> > > > > > > > > > >
>>> > > > > > > > > > > In order to avoid having the first digit (major) being
>>> > > bumped
>>> > > > > too
>>> > > > > > > > > > > often (TP3 shall remain TP3!), a variation could be:
>>> > > > > > > > > > > marketing.major.minor.patch (downside to that is 4
>>> digits
>>> > > > > > > versioning
>>> > > > > > > > > > > instead of 3). For example, adding a new Gremlin step
>>> > would
>>> > > > > bump
>>> > > > > > > > minor
>>> > > > > > > > > > > while changing a step signature in a
>>> > backward-incompatible
>>> > > > > manner
>>> > > > > > > > > > > would bump major.
>>> > > > > > > > > > >
>>> > > > > > > > > > > semver is very popular in the JavaScript/Node.js world
>>> > and
>>> > > > used
>>> > > > > > > > > > > extensively with npm (node package manager).
>>> > > > > > > > > > >
>>> > > > > > > > > > > Just some thoughts.
>>> > > > > > > > > > >
>>> > > > > > > > > > > Jean-Baptiste
>>> > > > > > > > > > >
>>> > > > > > > > > > > [1] http://semver.org/
>>> > > > > > > > > > >
>>> > > > > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
>>> > > > > > > > > spmallette@gmail.com>
>>>
>>> > > > > > > > > > > wrote:
>>> > > > > > > > > > > > I think it's worthwhile for us to do something we've
>>> > not
>>> > > > > really
>>> > > > > > > > done
>>> > > > > > > > > > > before
>>> > > > > > > > > > > > with any of the TinkerPop projects: use branches. We
>>> > > > > typically
>>> > > > > > > tend
>>> > > > > > > > > to
>>> > > > > > > > > > > use
>>> > > > > > > > > > > > branches for major refactoring that we might throw
>>> out,
>>> > > but
>>> > > > > not
>>> > > > > > > > > really
>>> > > > > > > > > > > for
>>> > > > > > > > > > > > release management. As we look past release 3.0.0, I
>>> > > think
>>> > > > we
>>> > > > > > > will
>>> > > > > > > > > want
>>> > > > > > > > > > > to
>>> > > > > > > > > > > > have the capability to do more frequent minor
>>> releases
>>> > > > (e.g.
>>> > > > > > > 3.0.1,
>>> > > > > > > > > > > 3.0.2,
>>> > > > > > > > > > > > etc) while still being able to do work for a future
>>> > 3.1.x
>>> > > > > line
>>> > > > > > of
>>> > > > > > > > > code.
>>> > > > > > > > > > > >
>>> > > > > > > > > > > > I think we can do this without too much change if we
>>> > > > > introduce
>>> > > > > > a
>>> > > > > > > > > simple
>>> > > > > > > > > > > > branch system.  Release branch rules would be
>>> simple -
>>> > we
>>> > > > > > create
>>> > > > > > > a
>>> > > > > > > > > new
>>> > > > > > > > > > > > branch from master called tp31 for the 3.1.x line of
>>> > > code.
>>> > > > > Any
>>> > > > > > > > > changes
>>> > > > > > > > > > > > that are "breaking", introduce significant risk, a
>>> > > "major"
>>> > > > > > > feature,
>>> > > > > > > > > > etc.
>>> > > > > > > > > > > > would be committed there.  All other changes, bug
>>> > fixes,
>>> > > > > > > > non-breaking
>>> > > > > > > > > > > > refactoring of major APIs, "minor" features, etc.
>>> would
>>> > > > > simply
>>> > > > > > > > commit
>>> > > > > > > > > > to
>>> > > > > > > > > > > > master.  the master branch effectively becomes the
>>> > 3.0.x
>>> > > > line
>>> > > > > > of
>>> > > > > > > > > code.
>>> > > > > > > > > > > > Under this approach the merge process is pretty
>>> simple
>>> > in
>>> > > > > that
>>> > > > > > we
>>> > > > > > > > > just
>>> > > > > > > > > > > > merge forward (i.e. master merges to to tp31).
>>> > > > > > > > > > > >
>>> > > > > > > > > > > > When the day comes that we're ready to release
>>> 3.1.0,
>>> > we
>>> > > > > merge
>>> > > > > > > tp31
>>> > > > > > > > > > back
>>> > > > > > > > > > > to
>>> > > > > > > > > > > > master and create tp32 and use the same model where
>>> the
>>> > > > 3.1.x
>>> > > > > > > line
>>> > > > > > > > is
>>> > > > > > > > > > > > master and the 3.2.x line is tp32.  Of course, under
>>> > this
>>> > > > > model
>>> > > > > > > we
>>> > > > > > > > > are
>>> > > > > > > > > > > > really supporting just the previous minor version,
>>> > which
>>> > > > for
>>> > > > > > > right
>>> > > > > > > > > now
>>> > > > > > > > > > > > seems acceptable to me.  That's more than what we've
>>> > ever
>>> > > > > > really
>>> > > > > > > > done
>>> > > > > > > > > > > well,
>>> > > > > > > > > > > > so that feels like a good starting point in my book.
>>> > > After
>>> > > > > we
>>> > > > > > > > > release
>>> > > > > > > > > > > > 3.1.0 we can revisit and decide if a more complex
>>> > > branching
>>> > > > > > > > strategy
>>> > > > > > > > > is
>>> > > > > > > > > > > > needed.
>>> > > > > > > > > > >
>>> > > > > > > > > >
>>> > > > > > > > >
>>> > > > > > > >
>>> > > > > > >
>>> > > > > >
>>> > > > >
>>> > > >
>>> > >
>>> >
>>>
>>
>>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

It also just occurred to me that the 3.0.1 portion of the CHANGELOG needs
to be replicated to the 3.1.0 section as the two may not be the same
(though should be for the most part).

On Fri, Jul 24, 2015 at 5:53 AM, Stephen Mallette <sp...@gmail.com>
wrote:

> Yup - I was playing with that.  Let's see if Marko has any thoughts on the
> matter.
>
> On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <ma...@gmail.com>
> wrote:
>
>> JIRA has a configurable "Release Notes" report.
>>
>>
>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
>>
>> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <sp...@gmail.com>
>> wrote:
>>
>> > I think i like that idea.  It would also force JIRA titles to be written
>> > better though so as to fit the flow of CHANGELOG....sometimes those are
>> > kinda slack.
>> >
>> > On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <
>> matthew.h.frantz@gmail.com>
>> > wrote:
>> >
>> > > Correct.  We would make manual additions to the CHANGELOG only to
>> augment
>> > > the JIRA report in some way, either to explain non-JIRA activities or
>> to
>> > > draw attention to particular JIRA issues that are significant (and we
>> > would
>> > > cite the JIRA ticket from the CHANGELOG for those).  The definition of
>> > > "significant" is discretionary.
>> > >
>> > > On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
>> spmallette@gmail.com
>> > >
>> > > wrote:
>> > >
>> > > > Are you suggesting that on release we rectify the JIRA report with
>> the
>> > > > CHANGELOG?  In that way, if something was done by way of JIRA we
>> > wouldn't
>> > > > have to enter a CHANGELOG entry manually, because on release we'd
>> pick
>> > it
>> > > > up via the JIRA report?
>> > > >
>> > > > On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
>> > matthew.h.frantz@gmail.com
>> > > >
>> > > > wrote:
>> > > >
>> > > > > Perhaps in the release process we could generate a JIRA report of
>> > > issues
>> > > > > marked as fixed in the specific version, and reserve the CHANGELOG
>> > for
>> > > > > significant changes and things that were not tracked through JIRA.
>> > > > >
>> > > > > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
>> > > spmallette@gmail.com>
>> > > > > wrote:
>> > > > >
>> > > > > > We have typically treated CHANGELOG rather unscientifically.
>> Make
>> > a
>> > > > > change
>> > > > > > of significance, then update the changelog for the appropriate
>> > > version.
>> > > > > I
>> > > > > > bat around the idea of including the issue ids all the time but
>> > > haven't
>> > > > > > wanted to start the trend of doing that.  Perhaps we do that and
>> > make
>> > > > it
>> > > > > > optional?? Not sure how others feel on that matter.
>> > > > > >
>> > > > > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
>> > > > > matthew.h.frantz@gmail.com>
>> > > > > > wrote:
>> > > > > >
>> > > > > > > I just merged my fix for TINKERPOP3-782 to both tp30 and
>> > master.  I
>> > > > > > didn't
>> > > > > > > touch CHANGELOG.  Do we do that for every bug fix?  I don't
>> see
>> > > > > > references
>> > > > > > > to JIRA artifacts in the CHANGELOG.
>> > > > > > >
>> > > > > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
>> > > > > spmallette@gmail.com>
>>
>> > > > > > > wrote:
>> > > > > > >
>> > > > > > > > Hi Matt,
>> > > > > > > >
>> > > > > > > > I have a PR currently targeted at tp30 (because it is a
>> > low-risk
>> > > > bug
>> > > > > > > fix).
>> > > > > > > > > I know that we don't necessarily code review everything
>> that
>> > > goes
>> > > > > in,
>> > > > > > > but
>> > > > > > > > > since I'm relatively new, I wouldn't mind someone taking a
>> > peek
>> > > > at
>> > > > > > it,
>> > > > > > > > and
>> > > > > > > > > the verify that tp30 is the best target.
>> > > > > > > > >
>> > > > > > > >
>> > > > > > > > Right - no official code review.  We pretty much tend to
>> handle
>> > > it
>> > > > as
>> > > > > > you
>> > > > > > > > just did - on a case-by-case basis.
>> > > > > > > >
>> > > > > > > >
>> > > > > > > > > (I don't have permissions on the GitHub mirror for
>> > > > > > > incubating-tinkerpop.
>> > > > > > > > > Should I?)
>> > > > > > > > >
>> > > > > > > >
>> > > > > > > > I don't think you should - I don't have permissions either.
>> > > > > > > >
>> > > > > > > >
>> > > > > > > > > Also, after it is merged to tp30, is the process going to
>> be
>> > > > that I
>> > > > > > > would
>> > > > > > > > > also need to merge tp30 into master?  Or do we plan to
>> merge
>> > > only
>> > > > > > > > > occasionally?
>> > > > > > > >
>> > > > > > > >
>> > > > > > > > I've been the only person committing things to tp30 of any
>> > > > substance
>> > > > > so
>> > > > > > > > I've been doing it periodically, but generally speaking, I'd
>> > say
>> > > > that
>> > > > > > > it's
>> > > > > > > > best if the person who commits to tp30 merges to master
>> (unless
>> > > > it's
>> > > > > > > > something pretty trivial).  In that way the person who
>> > committed
>> > > to
>> > > > > > tp30
>> > > > > > > is
>> > > > > > > > responsible for ensuring proper integration with master.
>> > > > > > > >
>> > > > > > > >
>> > > > > > > >
>> > > > > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
>> > > > > > > matthew.h.frantz@gmail.com>
>>
>> > > > > > > > wrote:
>> > > > > > > >
>> > > > > > > > > I have a PR currently targeted at tp30 (because it is a
>> > > low-risk
>> > > > > bug
>> > > > > > > > fix).
>> > > > > > > > > I know that we don't necessarily code review everything
>> that
>> > > goes
>> > > > > in,
>> > > > > > > but
>> > > > > > > > > since I'm relatively new, I wouldn't mind someone taking a
>> > peek
>> > > > at
>> > > > > > it,
>> > > > > > > > and
>> > > > > > > > > the verify that tp30 is the best target.
>> > > > > > > > >
>> > > > > > > > > (I don't have permissions on the GitHub mirror for
>> > > > > > > incubating-tinkerpop.
>> > > > > > > > > Should I?)
>> > > > > > > > >
>> > > > > > > > > Also, after it is merged to tp30, is the process going to
>> be
>> > > > that I
>> > > > > > > would
>> > > > > > > > > also need to merge tp30 into master?  Or do we plan to
>> merge
>> > > only
>> > > > > > > > > occasionally?
>> > > > > > > > >
>> > > > > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
>> > > > > > > spmallette@gmail.com>
>>
>> > > > > > > > > wrote:
>> > > > > > > > >
>> > > > > > > > > > Thanks JB - i'm familiar with semver and I think the
>> idea
>> > is
>> > > to
>> > > > > > > follow
>> > > > > > > > it
>> > > > > > > > > > in principle, in that we will save API breaking change
>> for
>> > > the
>> > > > > > > "minor"
>> > > > > > > > > > version.   imo, we should stick to the three digit
>> system
>> > for
>> > > > now
>> > > > > > > but I
>> > > > > > > > > > guess it's worth considering what a "breaking change"
>> is in
>> > > our
>> > > > > > > > context.
>> > > > > > > > > >
>> > > > > > > > > > TinkerPop is "big" - it has both public and internal
>> APIs.
>> > > if
>> > > > i
>> > > > > > > change
>> > > > > > > > > the
>> > > > > > > > > > package name of an internal API in a patch release, I
>> > > wouldn't
>> > > > > > expect
>> > > > > > > > > that
>> > > > > > > > > > to break anyone and thus I'm not sure I'd consider that
>> a
>> > > > > breaking
>> > > > > > > > change
>> > > > > > > > > >  (though it's always interesting to see how folks find
>> > their
>> > > > way
>> > > > > > into
>> > > > > > > > > using
>> > > > > > > > > > our internal classes) .  To me the "breaking changes"
>> are
>> > > ones
>> > > > > that
>> > > > > > > > occur
>> > > > > > > > > > in the public classes (i.e. the ones people are likely
>> to
>> > > use)
>> > > > > > like:
>> > > > > > > > > > gremlin driver classes, structure API for vendors, step
>> > > classes
>> > > > > and
>> > > > > > > > > > GraphTraversal/GraphTraversalSource, etc. Changing those
>> > > > classes
>> > > > > in
>> > > > > > > > some
>> > > > > > > > > > way, would break the greatest percentage of users.  I'm
>> not
>> > > > sure
>> > > > > > how
>> > > > > > > > > others
>> > > > > > > > > > feel, but I tend to think of "breaking change" in that
>> more
>> > > > fuzzy
>> > > > > > > > > fashion.
>> > > > > > > > > >
>> > > > > > > > > >
>> > > > > > > > > >
>> > > > > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
>> > > > > > > > jbmusso@gmail.com>
>>
>> > > > > > > > > > wrote:
>> > > > > > > > > >
>> > > > > > > > > > > Related - have you considered using semantic
>> versioning
>> > [1]
>> > > > > > > > > > > (major.minor.patch)? Roughly, semver states that
>> breaking
>> > > > > changes
>> > > > > > > > > > > should bump major, new backward-compatible features
>> > should
>> > > > bump
>> > > > > > > minor
>> > > > > > > > > > > while bug fixes should bump patch. It also supports
>> > > > pre-release
>> > > > > > > > > > > version (-alpha, -incubating or -whatever suffixes).
>> > > > > > > > > > >
>> > > > > > > > > > > In order to avoid having the first digit (major) being
>> > > bumped
>> > > > > too
>> > > > > > > > > > > often (TP3 shall remain TP3!), a variation could be:
>> > > > > > > > > > > marketing.major.minor.patch (downside to that is 4
>> digits
>> > > > > > > versioning
>> > > > > > > > > > > instead of 3). For example, adding a new Gremlin step
>> > would
>> > > > > bump
>> > > > > > > > minor
>> > > > > > > > > > > while changing a step signature in a
>> > backward-incompatible
>> > > > > manner
>> > > > > > > > > > > would bump major.
>> > > > > > > > > > >
>> > > > > > > > > > > semver is very popular in the JavaScript/Node.js world
>> > and
>> > > > used
>> > > > > > > > > > > extensively with npm (node package manager).
>> > > > > > > > > > >
>> > > > > > > > > > > Just some thoughts.
>> > > > > > > > > > >
>> > > > > > > > > > > Jean-Baptiste
>> > > > > > > > > > >
>> > > > > > > > > > > [1] http://semver.org/
>> > > > > > > > > > >
>> > > > > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
>> > > > > > > > > spmallette@gmail.com>
>>
>> > > > > > > > > > > wrote:
>> > > > > > > > > > > > I think it's worthwhile for us to do something we've
>> > not
>> > > > > really
>> > > > > > > > done
>> > > > > > > > > > > before
>> > > > > > > > > > > > with any of the TinkerPop projects: use branches. We
>> > > > > typically
>> > > > > > > tend
>> > > > > > > > > to
>> > > > > > > > > > > use
>> > > > > > > > > > > > branches for major refactoring that we might throw
>> out,
>> > > but
>> > > > > not
>> > > > > > > > > really
>> > > > > > > > > > > for
>> > > > > > > > > > > > release management. As we look past release 3.0.0, I
>> > > think
>> > > > we
>> > > > > > > will
>> > > > > > > > > want
>> > > > > > > > > > > to
>> > > > > > > > > > > > have the capability to do more frequent minor
>> releases
>> > > > (e.g.
>> > > > > > > 3.0.1,
>> > > > > > > > > > > 3.0.2,
>> > > > > > > > > > > > etc) while still being able to do work for a future
>> > 3.1.x
>> > > > > line
>> > > > > > of
>> > > > > > > > > code.
>> > > > > > > > > > > >
>> > > > > > > > > > > > I think we can do this without too much change if we
>> > > > > introduce
>> > > > > > a
>> > > > > > > > > simple
>> > > > > > > > > > > > branch system.  Release branch rules would be
>> simple -
>> > we
>> > > > > > create
>> > > > > > > a
>> > > > > > > > > new
>> > > > > > > > > > > > branch from master called tp31 for the 3.1.x line of
>> > > code.
>> > > > > Any
>> > > > > > > > > changes
>> > > > > > > > > > > > that are "breaking", introduce significant risk, a
>> > > "major"
>> > > > > > > feature,
>> > > > > > > > > > etc.
>> > > > > > > > > > > > would be committed there.  All other changes, bug
>> > fixes,
>> > > > > > > > non-breaking
>> > > > > > > > > > > > refactoring of major APIs, "minor" features, etc.
>> would
>> > > > > simply
>> > > > > > > > commit
>> > > > > > > > > > to
>> > > > > > > > > > > > master.  the master branch effectively becomes the
>> > 3.0.x
>> > > > line
>> > > > > > of
>> > > > > > > > > code.
>> > > > > > > > > > > > Under this approach the merge process is pretty
>> simple
>> > in
>> > > > > that
>> > > > > > we
>> > > > > > > > > just
>> > > > > > > > > > > > merge forward (i.e. master merges to to tp31).
>> > > > > > > > > > > >
>> > > > > > > > > > > > When the day comes that we're ready to release
>> 3.1.0,
>> > we
>> > > > > merge
>> > > > > > > tp31
>> > > > > > > > > > back
>> > > > > > > > > > > to
>> > > > > > > > > > > > master and create tp32 and use the same model where
>> the
>> > > > 3.1.x
>> > > > > > > line
>> > > > > > > > is
>> > > > > > > > > > > > master and the 3.2.x line is tp32.  Of course, under
>> > this
>> > > > > model
>> > > > > > > we
>> > > > > > > > > are
>> > > > > > > > > > > > really supporting just the previous minor version,
>> > which
>> > > > for
>> > > > > > > right
>> > > > > > > > > now
>> > > > > > > > > > > > seems acceptable to me.  That's more than what we've
>> > ever
>> > > > > > really
>> > > > > > > > done
>> > > > > > > > > > > well,
>> > > > > > > > > > > > so that feels like a good starting point in my book.
>> > > After
>> > > > > we
>> > > > > > > > > release
>> > > > > > > > > > > > 3.1.0 we can revisit and decide if a more complex
>> > > branching
>> > > > > > > > strategy
>> > > > > > > > > is
>> > > > > > > > > > > > needed.
>> > > > > > > > > > >
>> > > > > > > > > >
>> > > > > > > > >
>> > > > > > > >
>> > > > > > >
>> > > > > >
>> > > > >
>> > > >
>> > >
>> >
>>
>
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

Yup - I was playing with that.  Let's see if Marko has any thoughts on the
matter.

On Thu, Jul 23, 2015 at 8:44 PM, Matt Frantz <ma...@gmail.com>
wrote:

> JIRA has a configurable "Release Notes" report.
>
>
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017
>
> On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > I think i like that idea.  It would also force JIRA titles to be written
> > better though so as to fit the flow of CHANGELOG....sometimes those are
> > kinda slack.
> >
> > On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <matthew.h.frantz@gmail.com
> >
> > wrote:
> >
> > > Correct.  We would make manual additions to the CHANGELOG only to
> augment
> > > the JIRA report in some way, either to explain non-JIRA activities or
> to
> > > draw attention to particular JIRA issues that are significant (and we
> > would
> > > cite the JIRA ticket from the CHANGELOG for those).  The definition of
> > > "significant" is discretionary.
> > >
> > > On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <
> spmallette@gmail.com
> > >
> > > wrote:
> > >
> > > > Are you suggesting that on release we rectify the JIRA report with
> the
> > > > CHANGELOG?  In that way, if something was done by way of JIRA we
> > wouldn't
> > > > have to enter a CHANGELOG entry manually, because on release we'd
> pick
> > it
> > > > up via the JIRA report?
> > > >
> > > > On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
> > matthew.h.frantz@gmail.com
> > > >
> > > > wrote:
> > > >
> > > > > Perhaps in the release process we could generate a JIRA report of
> > > issues
> > > > > marked as fixed in the specific version, and reserve the CHANGELOG
> > for
> > > > > significant changes and things that were not tracked through JIRA.
> > > > >
> > > > > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
> > > spmallette@gmail.com>
> > > > > wrote:
> > > > >
> > > > > > We have typically treated CHANGELOG rather unscientifically.
> Make
> > a
> > > > > change
> > > > > > of significance, then update the changelog for the appropriate
> > > version.
> > > > > I
> > > > > > bat around the idea of including the issue ids all the time but
> > > haven't
> > > > > > wanted to start the trend of doing that.  Perhaps we do that and
> > make
> > > > it
> > > > > > optional?? Not sure how others feel on that matter.
> > > > > >
> > > > > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> > > > > matthew.h.frantz@gmail.com>
> > > > > > wrote:
> > > > > >
> > > > > > > I just merged my fix for TINKERPOP3-782 to both tp30 and
> > master.  I
> > > > > > didn't
> > > > > > > touch CHANGELOG.  Do we do that for every bug fix?  I don't see
> > > > > > references
> > > > > > > to JIRA artifacts in the CHANGELOG.
> > > > > > >
> > > > > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> > > > > spmallette@gmail.com>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > Hi Matt,
> > > > > > > >
> > > > > > > > I have a PR currently targeted at tp30 (because it is a
> > low-risk
> > > > bug
> > > > > > > fix).
> > > > > > > > > I know that we don't necessarily code review everything
> that
> > > goes
> > > > > in,
> > > > > > > but
> > > > > > > > > since I'm relatively new, I wouldn't mind someone taking a
> > peek
> > > > at
> > > > > > it,
> > > > > > > > and
> > > > > > > > > the verify that tp30 is the best target.
> > > > > > > > >
> > > > > > > >
> > > > > > > > Right - no official code review.  We pretty much tend to
> handle
> > > it
> > > > as
> > > > > > you
> > > > > > > > just did - on a case-by-case basis.
> > > > > > > >
> > > > > > > >
> > > > > > > > > (I don't have permissions on the GitHub mirror for
> > > > > > > incubating-tinkerpop.
> > > > > > > > > Should I?)
> > > > > > > > >
> > > > > > > >
> > > > > > > > I don't think you should - I don't have permissions either.
> > > > > > > >
> > > > > > > >
> > > > > > > > > Also, after it is merged to tp30, is the process going to
> be
> > > > that I
> > > > > > > would
> > > > > > > > > also need to merge tp30 into master?  Or do we plan to
> merge
> > > only
> > > > > > > > > occasionally?
> > > > > > > >
> > > > > > > >
> > > > > > > > I've been the only person committing things to tp30 of any
> > > > substance
> > > > > so
> > > > > > > > I've been doing it periodically, but generally speaking, I'd
> > say
> > > > that
> > > > > > > it's
> > > > > > > > best if the person who commits to tp30 merges to master
> (unless
> > > > it's
> > > > > > > > something pretty trivial).  In that way the person who
> > committed
> > > to
> > > > > > tp30
> > > > > > > is
> > > > > > > > responsible for ensuring proper integration with master.
> > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> > > > > > > matthew.h.frantz@gmail.com>
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > I have a PR currently targeted at tp30 (because it is a
> > > low-risk
> > > > > bug
> > > > > > > > fix).
> > > > > > > > > I know that we don't necessarily code review everything
> that
> > > goes
> > > > > in,
> > > > > > > but
> > > > > > > > > since I'm relatively new, I wouldn't mind someone taking a
> > peek
> > > > at
> > > > > > it,
> > > > > > > > and
> > > > > > > > > the verify that tp30 is the best target.
> > > > > > > > >
> > > > > > > > > (I don't have permissions on the GitHub mirror for
> > > > > > > incubating-tinkerpop.
> > > > > > > > > Should I?)
> > > > > > > > >
> > > > > > > > > Also, after it is merged to tp30, is the process going to
> be
> > > > that I
> > > > > > > would
> > > > > > > > > also need to merge tp30 into master?  Or do we plan to
> merge
> > > only
> > > > > > > > > occasionally?
> > > > > > > > >
> > > > > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> > > > > > > spmallette@gmail.com>
> > > > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > > Thanks JB - i'm familiar with semver and I think the idea
> > is
> > > to
> > > > > > > follow
> > > > > > > > it
> > > > > > > > > > in principle, in that we will save API breaking change
> for
> > > the
> > > > > > > "minor"
> > > > > > > > > > version.   imo, we should stick to the three digit system
> > for
> > > > now
> > > > > > > but I
> > > > > > > > > > guess it's worth considering what a "breaking change" is
> in
> > > our
> > > > > > > > context.
> > > > > > > > > >
> > > > > > > > > > TinkerPop is "big" - it has both public and internal
> APIs.
> > > if
> > > > i
> > > > > > > change
> > > > > > > > > the
> > > > > > > > > > package name of an internal API in a patch release, I
> > > wouldn't
> > > > > > expect
> > > > > > > > > that
> > > > > > > > > > to break anyone and thus I'm not sure I'd consider that a
> > > > > breaking
> > > > > > > > change
> > > > > > > > > >  (though it's always interesting to see how folks find
> > their
> > > > way
> > > > > > into
> > > > > > > > > using
> > > > > > > > > > our internal classes) .  To me the "breaking changes" are
> > > ones
> > > > > that
> > > > > > > > occur
> > > > > > > > > > in the public classes (i.e. the ones people are likely to
> > > use)
> > > > > > like:
> > > > > > > > > > gremlin driver classes, structure API for vendors, step
> > > classes
> > > > > and
> > > > > > > > > > GraphTraversal/GraphTraversalSource, etc. Changing those
> > > > classes
> > > > > in
> > > > > > > > some
> > > > > > > > > > way, would break the greatest percentage of users.  I'm
> not
> > > > sure
> > > > > > how
> > > > > > > > > others
> > > > > > > > > > feel, but I tend to think of "breaking change" in that
> more
> > > > fuzzy
> > > > > > > > > fashion.
> > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
> > > > > > > > jbmusso@gmail.com>
> > > > > > > > > > wrote:
> > > > > > > > > >
> > > > > > > > > > > Related - have you considered using semantic versioning
> > [1]
> > > > > > > > > > > (major.minor.patch)? Roughly, semver states that
> breaking
> > > > > changes
> > > > > > > > > > > should bump major, new backward-compatible features
> > should
> > > > bump
> > > > > > > minor
> > > > > > > > > > > while bug fixes should bump patch. It also supports
> > > > pre-release
> > > > > > > > > > > version (-alpha, -incubating or -whatever suffixes).
> > > > > > > > > > >
> > > > > > > > > > > In order to avoid having the first digit (major) being
> > > bumped
> > > > > too
> > > > > > > > > > > often (TP3 shall remain TP3!), a variation could be:
> > > > > > > > > > > marketing.major.minor.patch (downside to that is 4
> digits
> > > > > > > versioning
> > > > > > > > > > > instead of 3). For example, adding a new Gremlin step
> > would
> > > > > bump
> > > > > > > > minor
> > > > > > > > > > > while changing a step signature in a
> > backward-incompatible
> > > > > manner
> > > > > > > > > > > would bump major.
> > > > > > > > > > >
> > > > > > > > > > > semver is very popular in the JavaScript/Node.js world
> > and
> > > > used
> > > > > > > > > > > extensively with npm (node package manager).
> > > > > > > > > > >
> > > > > > > > > > > Just some thoughts.
> > > > > > > > > > >
> > > > > > > > > > > Jean-Baptiste
> > > > > > > > > > >
> > > > > > > > > > > [1] http://semver.org/
> > > > > > > > > > >
> > > > > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> > > > > > > > > spmallette@gmail.com>
> > > > > > > > > > > wrote:
> > > > > > > > > > > > I think it's worthwhile for us to do something we've
> > not
> > > > > really
> > > > > > > > done
> > > > > > > > > > > before
> > > > > > > > > > > > with any of the TinkerPop projects: use branches. We
> > > > > typically
> > > > > > > tend
> > > > > > > > > to
> > > > > > > > > > > use
> > > > > > > > > > > > branches for major refactoring that we might throw
> out,
> > > but
> > > > > not
> > > > > > > > > really
> > > > > > > > > > > for
> > > > > > > > > > > > release management. As we look past release 3.0.0, I
> > > think
> > > > we
> > > > > > > will
> > > > > > > > > want
> > > > > > > > > > > to
> > > > > > > > > > > > have the capability to do more frequent minor
> releases
> > > > (e.g.
> > > > > > > 3.0.1,
> > > > > > > > > > > 3.0.2,
> > > > > > > > > > > > etc) while still being able to do work for a future
> > 3.1.x
> > > > > line
> > > > > > of
> > > > > > > > > code.
> > > > > > > > > > > >
> > > > > > > > > > > > I think we can do this without too much change if we
> > > > > introduce
> > > > > > a
> > > > > > > > > simple
> > > > > > > > > > > > branch system.  Release branch rules would be simple
> -
> > we
> > > > > > create
> > > > > > > a
> > > > > > > > > new
> > > > > > > > > > > > branch from master called tp31 for the 3.1.x line of
> > > code.
> > > > > Any
> > > > > > > > > changes
> > > > > > > > > > > > that are "breaking", introduce significant risk, a
> > > "major"
> > > > > > > feature,
> > > > > > > > > > etc.
> > > > > > > > > > > > would be committed there.  All other changes, bug
> > fixes,
> > > > > > > > non-breaking
> > > > > > > > > > > > refactoring of major APIs, "minor" features, etc.
> would
> > > > > simply
> > > > > > > > commit
> > > > > > > > > > to
> > > > > > > > > > > > master.  the master branch effectively becomes the
> > 3.0.x
> > > > line
> > > > > > of
> > > > > > > > > code.
> > > > > > > > > > > > Under this approach the merge process is pretty
> simple
> > in
> > > > > that
> > > > > > we
> > > > > > > > > just
> > > > > > > > > > > > merge forward (i.e. master merges to to tp31).
> > > > > > > > > > > >
> > > > > > > > > > > > When the day comes that we're ready to release 3.1.0,
> > we
> > > > > merge
> > > > > > > tp31
> > > > > > > > > > back
> > > > > > > > > > > to
> > > > > > > > > > > > master and create tp32 and use the same model where
> the
> > > > 3.1.x
> > > > > > > line
> > > > > > > > is
> > > > > > > > > > > > master and the 3.2.x line is tp32.  Of course, under
> > this
> > > > > model
> > > > > > > we
> > > > > > > > > are
> > > > > > > > > > > > really supporting just the previous minor version,
> > which
> > > > for
> > > > > > > right
> > > > > > > > > now
> > > > > > > > > > > > seems acceptable to me.  That's more than what we've
> > ever
> > > > > > really
> > > > > > > > done
> > > > > > > > > > > well,
> > > > > > > > > > > > so that feels like a good starting point in my book.
> > > After
> > > > > we
> > > > > > > > > release
> > > > > > > > > > > > 3.1.0 we can revisit and decide if a more complex
> > > branching
> > > > > > > > strategy
> > > > > > > > > is
> > > > > > > > > > > > needed.
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

Re: branching after GA

[Matt Frantz <ma...@gmail.com>]

JIRA has a configurable "Release Notes" report.

https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316520&version=12333017

On Thu, Jul 23, 2015 at 12:32 PM, Stephen Mallette <sp...@gmail.com>
wrote:

> I think i like that idea.  It would also force JIRA titles to be written
> better though so as to fit the flow of CHANGELOG....sometimes those are
> kinda slack.
>
> On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <ma...@gmail.com>
> wrote:
>
> > Correct.  We would make manual additions to the CHANGELOG only to augment
> > the JIRA report in some way, either to explain non-JIRA activities or to
> > draw attention to particular JIRA issues that are significant (and we
> would
> > cite the JIRA ticket from the CHANGELOG for those).  The definition of
> > "significant" is discretionary.
> >
> > On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <spmallette@gmail.com
> >
> > wrote:
> >
> > > Are you suggesting that on release we rectify the JIRA report with the
> > > CHANGELOG?  In that way, if something was done by way of JIRA we
> wouldn't
> > > have to enter a CHANGELOG entry manually, because on release we'd pick
> it
> > > up via the JIRA report?
> > >
> > > On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <
> matthew.h.frantz@gmail.com
> > >
> > > wrote:
> > >
> > > > Perhaps in the release process we could generate a JIRA report of
> > issues
> > > > marked as fixed in the specific version, and reserve the CHANGELOG
> for
> > > > significant changes and things that were not tracked through JIRA.
> > > >
> > > > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
> > spmallette@gmail.com>
> > > > wrote:
> > > >
> > > > > We have typically treated CHANGELOG rather unscientifically.  Make
> a
> > > > change
> > > > > of significance, then update the changelog for the appropriate
> > version.
> > > > I
> > > > > bat around the idea of including the issue ids all the time but
> > haven't
> > > > > wanted to start the trend of doing that.  Perhaps we do that and
> make
> > > it
> > > > > optional?? Not sure how others feel on that matter.
> > > > >
> > > > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> > > > matthew.h.frantz@gmail.com>
> > > > > wrote:
> > > > >
> > > > > > I just merged my fix for TINKERPOP3-782 to both tp30 and
> master.  I
> > > > > didn't
> > > > > > touch CHANGELOG.  Do we do that for every bug fix?  I don't see
> > > > > references
> > > > > > to JIRA artifacts in the CHANGELOG.
> > > > > >
> > > > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> > > > spmallette@gmail.com>
> > > > > > wrote:
> > > > > >
> > > > > > > Hi Matt,
> > > > > > >
> > > > > > > I have a PR currently targeted at tp30 (because it is a
> low-risk
> > > bug
> > > > > > fix).
> > > > > > > > I know that we don't necessarily code review everything that
> > goes
> > > > in,
> > > > > > but
> > > > > > > > since I'm relatively new, I wouldn't mind someone taking a
> peek
> > > at
> > > > > it,
> > > > > > > and
> > > > > > > > the verify that tp30 is the best target.
> > > > > > > >
> > > > > > >
> > > > > > > Right - no official code review.  We pretty much tend to handle
> > it
> > > as
> > > > > you
> > > > > > > just did - on a case-by-case basis.
> > > > > > >
> > > > > > >
> > > > > > > > (I don't have permissions on the GitHub mirror for
> > > > > > incubating-tinkerpop.
> > > > > > > > Should I?)
> > > > > > > >
> > > > > > >
> > > > > > > I don't think you should - I don't have permissions either.
> > > > > > >
> > > > > > >
> > > > > > > > Also, after it is merged to tp30, is the process going to be
> > > that I
> > > > > > would
> > > > > > > > also need to merge tp30 into master?  Or do we plan to merge
> > only
> > > > > > > > occasionally?
> > > > > > >
> > > > > > >
> > > > > > > I've been the only person committing things to tp30 of any
> > > substance
> > > > so
> > > > > > > I've been doing it periodically, but generally speaking, I'd
> say
> > > that
> > > > > > it's
> > > > > > > best if the person who commits to tp30 merges to master (unless
> > > it's
> > > > > > > something pretty trivial).  In that way the person who
> committed
> > to
> > > > > tp30
> > > > > > is
> > > > > > > responsible for ensuring proper integration with master.
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> > > > > > matthew.h.frantz@gmail.com>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > I have a PR currently targeted at tp30 (because it is a
> > low-risk
> > > > bug
> > > > > > > fix).
> > > > > > > > I know that we don't necessarily code review everything that
> > goes
> > > > in,
> > > > > > but
> > > > > > > > since I'm relatively new, I wouldn't mind someone taking a
> peek
> > > at
> > > > > it,
> > > > > > > and
> > > > > > > > the verify that tp30 is the best target.
> > > > > > > >
> > > > > > > > (I don't have permissions on the GitHub mirror for
> > > > > > incubating-tinkerpop.
> > > > > > > > Should I?)
> > > > > > > >
> > > > > > > > Also, after it is merged to tp30, is the process going to be
> > > that I
> > > > > > would
> > > > > > > > also need to merge tp30 into master?  Or do we plan to merge
> > only
> > > > > > > > occasionally?
> > > > > > > >
> > > > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> > > > > > spmallette@gmail.com>
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > Thanks JB - i'm familiar with semver and I think the idea
> is
> > to
> > > > > > follow
> > > > > > > it
> > > > > > > > > in principle, in that we will save API breaking change for
> > the
> > > > > > "minor"
> > > > > > > > > version.   imo, we should stick to the three digit system
> for
> > > now
> > > > > > but I
> > > > > > > > > guess it's worth considering what a "breaking change" is in
> > our
> > > > > > > context.
> > > > > > > > >
> > > > > > > > > TinkerPop is "big" - it has both public and internal APIs.
> > if
> > > i
> > > > > > change
> > > > > > > > the
> > > > > > > > > package name of an internal API in a patch release, I
> > wouldn't
> > > > > expect
> > > > > > > > that
> > > > > > > > > to break anyone and thus I'm not sure I'd consider that a
> > > > breaking
> > > > > > > change
> > > > > > > > >  (though it's always interesting to see how folks find
> their
> > > way
> > > > > into
> > > > > > > > using
> > > > > > > > > our internal classes) .  To me the "breaking changes" are
> > ones
> > > > that
> > > > > > > occur
> > > > > > > > > in the public classes (i.e. the ones people are likely to
> > use)
> > > > > like:
> > > > > > > > > gremlin driver classes, structure API for vendors, step
> > classes
> > > > and
> > > > > > > > > GraphTraversal/GraphTraversalSource, etc. Changing those
> > > classes
> > > > in
> > > > > > > some
> > > > > > > > > way, would break the greatest percentage of users.  I'm not
> > > sure
> > > > > how
> > > > > > > > others
> > > > > > > > > feel, but I tend to think of "breaking change" in that more
> > > fuzzy
> > > > > > > > fashion.
> > > > > > > > >
> > > > > > > > >
> > > > > > > > >
> > > > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
> > > > > > > jbmusso@gmail.com>
> > > > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > > Related - have you considered using semantic versioning
> [1]
> > > > > > > > > > (major.minor.patch)? Roughly, semver states that breaking
> > > > changes
> > > > > > > > > > should bump major, new backward-compatible features
> should
> > > bump
> > > > > > minor
> > > > > > > > > > while bug fixes should bump patch. It also supports
> > > pre-release
> > > > > > > > > > version (-alpha, -incubating or -whatever suffixes).
> > > > > > > > > >
> > > > > > > > > > In order to avoid having the first digit (major) being
> > bumped
> > > > too
> > > > > > > > > > often (TP3 shall remain TP3!), a variation could be:
> > > > > > > > > > marketing.major.minor.patch (downside to that is 4 digits
> > > > > > versioning
> > > > > > > > > > instead of 3). For example, adding a new Gremlin step
> would
> > > > bump
> > > > > > > minor
> > > > > > > > > > while changing a step signature in a
> backward-incompatible
> > > > manner
> > > > > > > > > > would bump major.
> > > > > > > > > >
> > > > > > > > > > semver is very popular in the JavaScript/Node.js world
> and
> > > used
> > > > > > > > > > extensively with npm (node package manager).
> > > > > > > > > >
> > > > > > > > > > Just some thoughts.
> > > > > > > > > >
> > > > > > > > > > Jean-Baptiste
> > > > > > > > > >
> > > > > > > > > > [1] http://semver.org/
> > > > > > > > > >
> > > > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> > > > > > > > spmallette@gmail.com>
> > > > > > > > > > wrote:
> > > > > > > > > > > I think it's worthwhile for us to do something we've
> not
> > > > really
> > > > > > > done
> > > > > > > > > > before
> > > > > > > > > > > with any of the TinkerPop projects: use branches. We
> > > > typically
> > > > > > tend
> > > > > > > > to
> > > > > > > > > > use
> > > > > > > > > > > branches for major refactoring that we might throw out,
> > but
> > > > not
> > > > > > > > really
> > > > > > > > > > for
> > > > > > > > > > > release management. As we look past release 3.0.0, I
> > think
> > > we
> > > > > > will
> > > > > > > > want
> > > > > > > > > > to
> > > > > > > > > > > have the capability to do more frequent minor releases
> > > (e.g.
> > > > > > 3.0.1,
> > > > > > > > > > 3.0.2,
> > > > > > > > > > > etc) while still being able to do work for a future
> 3.1.x
> > > > line
> > > > > of
> > > > > > > > code.
> > > > > > > > > > >
> > > > > > > > > > > I think we can do this without too much change if we
> > > > introduce
> > > > > a
> > > > > > > > simple
> > > > > > > > > > > branch system.  Release branch rules would be simple -
> we
> > > > > create
> > > > > > a
> > > > > > > > new
> > > > > > > > > > > branch from master called tp31 for the 3.1.x line of
> > code.
> > > > Any
> > > > > > > > changes
> > > > > > > > > > > that are "breaking", introduce significant risk, a
> > "major"
> > > > > > feature,
> > > > > > > > > etc.
> > > > > > > > > > > would be committed there.  All other changes, bug
> fixes,
> > > > > > > non-breaking
> > > > > > > > > > > refactoring of major APIs, "minor" features, etc. would
> > > > simply
> > > > > > > commit
> > > > > > > > > to
> > > > > > > > > > > master.  the master branch effectively becomes the
> 3.0.x
> > > line
> > > > > of
> > > > > > > > code.
> > > > > > > > > > > Under this approach the merge process is pretty simple
> in
> > > > that
> > > > > we
> > > > > > > > just
> > > > > > > > > > > merge forward (i.e. master merges to to tp31).
> > > > > > > > > > >
> > > > > > > > > > > When the day comes that we're ready to release 3.1.0,
> we
> > > > merge
> > > > > > tp31
> > > > > > > > > back
> > > > > > > > > > to
> > > > > > > > > > > master and create tp32 and use the same model where the
> > > 3.1.x
> > > > > > line
> > > > > > > is
> > > > > > > > > > > master and the 3.2.x line is tp32.  Of course, under
> this
> > > > model
> > > > > > we
> > > > > > > > are
> > > > > > > > > > > really supporting just the previous minor version,
> which
> > > for
> > > > > > right
> > > > > > > > now
> > > > > > > > > > > seems acceptable to me.  That's more than what we've
> ever
> > > > > really
> > > > > > > done
> > > > > > > > > > well,
> > > > > > > > > > > so that feels like a good starting point in my book.
> > After
> > > > we
> > > > > > > > release
> > > > > > > > > > > 3.1.0 we can revisit and decide if a more complex
> > branching
> > > > > > > strategy
> > > > > > > > is
> > > > > > > > > > > needed.
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

I think i like that idea.  It would also force JIRA titles to be written
better though so as to fit the flow of CHANGELOG....sometimes those are
kinda slack.

On Thu, Jul 23, 2015 at 2:20 PM, Matt Frantz <ma...@gmail.com>
wrote:

> Correct.  We would make manual additions to the CHANGELOG only to augment
> the JIRA report in some way, either to explain non-JIRA activities or to
> draw attention to particular JIRA issues that are significant (and we would
> cite the JIRA ticket from the CHANGELOG for those).  The definition of
> "significant" is discretionary.
>
> On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > Are you suggesting that on release we rectify the JIRA report with the
> > CHANGELOG?  In that way, if something was done by way of JIRA we wouldn't
> > have to enter a CHANGELOG entry manually, because on release we'd pick it
> > up via the JIRA report?
> >
> > On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <matthew.h.frantz@gmail.com
> >
> > wrote:
> >
> > > Perhaps in the release process we could generate a JIRA report of
> issues
> > > marked as fixed in the specific version, and reserve the CHANGELOG for
> > > significant changes and things that were not tracked through JIRA.
> > >
> > > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <
> spmallette@gmail.com>
> > > wrote:
> > >
> > > > We have typically treated CHANGELOG rather unscientifically.  Make a
> > > change
> > > > of significance, then update the changelog for the appropriate
> version.
> > > I
> > > > bat around the idea of including the issue ids all the time but
> haven't
> > > > wanted to start the trend of doing that.  Perhaps we do that and make
> > it
> > > > optional?? Not sure how others feel on that matter.
> > > >
> > > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> > > matthew.h.frantz@gmail.com>
> > > > wrote:
> > > >
> > > > > I just merged my fix for TINKERPOP3-782 to both tp30 and master.  I
> > > > didn't
> > > > > touch CHANGELOG.  Do we do that for every bug fix?  I don't see
> > > > references
> > > > > to JIRA artifacts in the CHANGELOG.
> > > > >
> > > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> > > spmallette@gmail.com>
> > > > > wrote:
> > > > >
> > > > > > Hi Matt,
> > > > > >
> > > > > > I have a PR currently targeted at tp30 (because it is a low-risk
> > bug
> > > > > fix).
> > > > > > > I know that we don't necessarily code review everything that
> goes
> > > in,
> > > > > but
> > > > > > > since I'm relatively new, I wouldn't mind someone taking a peek
> > at
> > > > it,
> > > > > > and
> > > > > > > the verify that tp30 is the best target.
> > > > > > >
> > > > > >
> > > > > > Right - no official code review.  We pretty much tend to handle
> it
> > as
> > > > you
> > > > > > just did - on a case-by-case basis.
> > > > > >
> > > > > >
> > > > > > > (I don't have permissions on the GitHub mirror for
> > > > > incubating-tinkerpop.
> > > > > > > Should I?)
> > > > > > >
> > > > > >
> > > > > > I don't think you should - I don't have permissions either.
> > > > > >
> > > > > >
> > > > > > > Also, after it is merged to tp30, is the process going to be
> > that I
> > > > > would
> > > > > > > also need to merge tp30 into master?  Or do we plan to merge
> only
> > > > > > > occasionally?
> > > > > >
> > > > > >
> > > > > > I've been the only person committing things to tp30 of any
> > substance
> > > so
> > > > > > I've been doing it periodically, but generally speaking, I'd say
> > that
> > > > > it's
> > > > > > best if the person who commits to tp30 merges to master (unless
> > it's
> > > > > > something pretty trivial).  In that way the person who committed
> to
> > > > tp30
> > > > > is
> > > > > > responsible for ensuring proper integration with master.
> > > > > >
> > > > > >
> > > > > >
> > > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> > > > > matthew.h.frantz@gmail.com>
> > > > > > wrote:
> > > > > >
> > > > > > > I have a PR currently targeted at tp30 (because it is a
> low-risk
> > > bug
> > > > > > fix).
> > > > > > > I know that we don't necessarily code review everything that
> goes
> > > in,
> > > > > but
> > > > > > > since I'm relatively new, I wouldn't mind someone taking a peek
> > at
> > > > it,
> > > > > > and
> > > > > > > the verify that tp30 is the best target.
> > > > > > >
> > > > > > > (I don't have permissions on the GitHub mirror for
> > > > > incubating-tinkerpop.
> > > > > > > Should I?)
> > > > > > >
> > > > > > > Also, after it is merged to tp30, is the process going to be
> > that I
> > > > > would
> > > > > > > also need to merge tp30 into master?  Or do we plan to merge
> only
> > > > > > > occasionally?
> > > > > > >
> > > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> > > > > spmallette@gmail.com>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > Thanks JB - i'm familiar with semver and I think the idea is
> to
> > > > > follow
> > > > > > it
> > > > > > > > in principle, in that we will save API breaking change for
> the
> > > > > "minor"
> > > > > > > > version.   imo, we should stick to the three digit system for
> > now
> > > > > but I
> > > > > > > > guess it's worth considering what a "breaking change" is in
> our
> > > > > > context.
> > > > > > > >
> > > > > > > > TinkerPop is "big" - it has both public and internal APIs.
> if
> > i
> > > > > change
> > > > > > > the
> > > > > > > > package name of an internal API in a patch release, I
> wouldn't
> > > > expect
> > > > > > > that
> > > > > > > > to break anyone and thus I'm not sure I'd consider that a
> > > breaking
> > > > > > change
> > > > > > > >  (though it's always interesting to see how folks find their
> > way
> > > > into
> > > > > > > using
> > > > > > > > our internal classes) .  To me the "breaking changes" are
> ones
> > > that
> > > > > > occur
> > > > > > > > in the public classes (i.e. the ones people are likely to
> use)
> > > > like:
> > > > > > > > gremlin driver classes, structure API for vendors, step
> classes
> > > and
> > > > > > > > GraphTraversal/GraphTraversalSource, etc. Changing those
> > classes
> > > in
> > > > > > some
> > > > > > > > way, would break the greatest percentage of users.  I'm not
> > sure
> > > > how
> > > > > > > others
> > > > > > > > feel, but I tend to think of "breaking change" in that more
> > fuzzy
> > > > > > > fashion.
> > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
> > > > > > jbmusso@gmail.com>
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > Related - have you considered using semantic versioning [1]
> > > > > > > > > (major.minor.patch)? Roughly, semver states that breaking
> > > changes
> > > > > > > > > should bump major, new backward-compatible features should
> > bump
> > > > > minor
> > > > > > > > > while bug fixes should bump patch. It also supports
> > pre-release
> > > > > > > > > version (-alpha, -incubating or -whatever suffixes).
> > > > > > > > >
> > > > > > > > > In order to avoid having the first digit (major) being
> bumped
> > > too
> > > > > > > > > often (TP3 shall remain TP3!), a variation could be:
> > > > > > > > > marketing.major.minor.patch (downside to that is 4 digits
> > > > > versioning
> > > > > > > > > instead of 3). For example, adding a new Gremlin step would
> > > bump
> > > > > > minor
> > > > > > > > > while changing a step signature in a backward-incompatible
> > > manner
> > > > > > > > > would bump major.
> > > > > > > > >
> > > > > > > > > semver is very popular in the JavaScript/Node.js world and
> > used
> > > > > > > > > extensively with npm (node package manager).
> > > > > > > > >
> > > > > > > > > Just some thoughts.
> > > > > > > > >
> > > > > > > > > Jean-Baptiste
> > > > > > > > >
> > > > > > > > > [1] http://semver.org/
> > > > > > > > >
> > > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> > > > > > > spmallette@gmail.com>
> > > > > > > > > wrote:
> > > > > > > > > > I think it's worthwhile for us to do something we've not
> > > really
> > > > > > done
> > > > > > > > > before
> > > > > > > > > > with any of the TinkerPop projects: use branches. We
> > > typically
> > > > > tend
> > > > > > > to
> > > > > > > > > use
> > > > > > > > > > branches for major refactoring that we might throw out,
> but
> > > not
> > > > > > > really
> > > > > > > > > for
> > > > > > > > > > release management. As we look past release 3.0.0, I
> think
> > we
> > > > > will
> > > > > > > want
> > > > > > > > > to
> > > > > > > > > > have the capability to do more frequent minor releases
> > (e.g.
> > > > > 3.0.1,
> > > > > > > > > 3.0.2,
> > > > > > > > > > etc) while still being able to do work for a future 3.1.x
> > > line
> > > > of
> > > > > > > code.
> > > > > > > > > >
> > > > > > > > > > I think we can do this without too much change if we
> > > introduce
> > > > a
> > > > > > > simple
> > > > > > > > > > branch system.  Release branch rules would be simple - we
> > > > create
> > > > > a
> > > > > > > new
> > > > > > > > > > branch from master called tp31 for the 3.1.x line of
> code.
> > > Any
> > > > > > > changes
> > > > > > > > > > that are "breaking", introduce significant risk, a
> "major"
> > > > > feature,
> > > > > > > > etc.
> > > > > > > > > > would be committed there.  All other changes, bug fixes,
> > > > > > non-breaking
> > > > > > > > > > refactoring of major APIs, "minor" features, etc. would
> > > simply
> > > > > > commit
> > > > > > > > to
> > > > > > > > > > master.  the master branch effectively becomes the 3.0.x
> > line
> > > > of
> > > > > > > code.
> > > > > > > > > > Under this approach the merge process is pretty simple in
> > > that
> > > > we
> > > > > > > just
> > > > > > > > > > merge forward (i.e. master merges to to tp31).
> > > > > > > > > >
> > > > > > > > > > When the day comes that we're ready to release 3.1.0, we
> > > merge
> > > > > tp31
> > > > > > > > back
> > > > > > > > > to
> > > > > > > > > > master and create tp32 and use the same model where the
> > 3.1.x
> > > > > line
> > > > > > is
> > > > > > > > > > master and the 3.2.x line is tp32.  Of course, under this
> > > model
> > > > > we
> > > > > > > are
> > > > > > > > > > really supporting just the previous minor version, which
> > for
> > > > > right
> > > > > > > now
> > > > > > > > > > seems acceptable to me.  That's more than what we've ever
> > > > really
> > > > > > done
> > > > > > > > > well,
> > > > > > > > > > so that feels like a good starting point in my book.
> After
> > > we
> > > > > > > release
> > > > > > > > > > 3.1.0 we can revisit and decide if a more complex
> branching
> > > > > > strategy
> > > > > > > is
> > > > > > > > > > needed.
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

Re: branching after GA

[Matt Frantz <ma...@gmail.com>]

Correct.  We would make manual additions to the CHANGELOG only to augment
the JIRA report in some way, either to explain non-JIRA activities or to
draw attention to particular JIRA issues that are significant (and we would
cite the JIRA ticket from the CHANGELOG for those).  The definition of
"significant" is discretionary.

On Thu, Jul 23, 2015 at 10:31 AM, Stephen Mallette <sp...@gmail.com>
wrote:

> Are you suggesting that on release we rectify the JIRA report with the
> CHANGELOG?  In that way, if something was done by way of JIRA we wouldn't
> have to enter a CHANGELOG entry manually, because on release we'd pick it
> up via the JIRA report?
>
> On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <ma...@gmail.com>
> wrote:
>
> > Perhaps in the release process we could generate a JIRA report of issues
> > marked as fixed in the specific version, and reserve the CHANGELOG for
> > significant changes and things that were not tracked through JIRA.
> >
> > On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> >
> > > We have typically treated CHANGELOG rather unscientifically.  Make a
> > change
> > > of significance, then update the changelog for the appropriate version.
> > I
> > > bat around the idea of including the issue ids all the time but haven't
> > > wanted to start the trend of doing that.  Perhaps we do that and make
> it
> > > optional?? Not sure how others feel on that matter.
> > >
> > > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> > matthew.h.frantz@gmail.com>
> > > wrote:
> > >
> > > > I just merged my fix for TINKERPOP3-782 to both tp30 and master.  I
> > > didn't
> > > > touch CHANGELOG.  Do we do that for every bug fix?  I don't see
> > > references
> > > > to JIRA artifacts in the CHANGELOG.
> > > >
> > > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> > spmallette@gmail.com>
> > > > wrote:
> > > >
> > > > > Hi Matt,
> > > > >
> > > > > I have a PR currently targeted at tp30 (because it is a low-risk
> bug
> > > > fix).
> > > > > > I know that we don't necessarily code review everything that goes
> > in,
> > > > but
> > > > > > since I'm relatively new, I wouldn't mind someone taking a peek
> at
> > > it,
> > > > > and
> > > > > > the verify that tp30 is the best target.
> > > > > >
> > > > >
> > > > > Right - no official code review.  We pretty much tend to handle it
> as
> > > you
> > > > > just did - on a case-by-case basis.
> > > > >
> > > > >
> > > > > > (I don't have permissions on the GitHub mirror for
> > > > incubating-tinkerpop.
> > > > > > Should I?)
> > > > > >
> > > > >
> > > > > I don't think you should - I don't have permissions either.
> > > > >
> > > > >
> > > > > > Also, after it is merged to tp30, is the process going to be
> that I
> > > > would
> > > > > > also need to merge tp30 into master?  Or do we plan to merge only
> > > > > > occasionally?
> > > > >
> > > > >
> > > > > I've been the only person committing things to tp30 of any
> substance
> > so
> > > > > I've been doing it periodically, but generally speaking, I'd say
> that
> > > > it's
> > > > > best if the person who commits to tp30 merges to master (unless
> it's
> > > > > something pretty trivial).  In that way the person who committed to
> > > tp30
> > > > is
> > > > > responsible for ensuring proper integration with master.
> > > > >
> > > > >
> > > > >
> > > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> > > > matthew.h.frantz@gmail.com>
> > > > > wrote:
> > > > >
> > > > > > I have a PR currently targeted at tp30 (because it is a low-risk
> > bug
> > > > > fix).
> > > > > > I know that we don't necessarily code review everything that goes
> > in,
> > > > but
> > > > > > since I'm relatively new, I wouldn't mind someone taking a peek
> at
> > > it,
> > > > > and
> > > > > > the verify that tp30 is the best target.
> > > > > >
> > > > > > (I don't have permissions on the GitHub mirror for
> > > > incubating-tinkerpop.
> > > > > > Should I?)
> > > > > >
> > > > > > Also, after it is merged to tp30, is the process going to be
> that I
> > > > would
> > > > > > also need to merge tp30 into master?  Or do we plan to merge only
> > > > > > occasionally?
> > > > > >
> > > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> > > > spmallette@gmail.com>
> > > > > > wrote:
> > > > > >
> > > > > > > Thanks JB - i'm familiar with semver and I think the idea is to
> > > > follow
> > > > > it
> > > > > > > in principle, in that we will save API breaking change for the
> > > > "minor"
> > > > > > > version.   imo, we should stick to the three digit system for
> now
> > > > but I
> > > > > > > guess it's worth considering what a "breaking change" is in our
> > > > > context.
> > > > > > >
> > > > > > > TinkerPop is "big" - it has both public and internal APIs.  if
> i
> > > > change
> > > > > > the
> > > > > > > package name of an internal API in a patch release, I wouldn't
> > > expect
> > > > > > that
> > > > > > > to break anyone and thus I'm not sure I'd consider that a
> > breaking
> > > > > change
> > > > > > >  (though it's always interesting to see how folks find their
> way
> > > into
> > > > > > using
> > > > > > > our internal classes) .  To me the "breaking changes" are ones
> > that
> > > > > occur
> > > > > > > in the public classes (i.e. the ones people are likely to use)
> > > like:
> > > > > > > gremlin driver classes, structure API for vendors, step classes
> > and
> > > > > > > GraphTraversal/GraphTraversalSource, etc. Changing those
> classes
> > in
> > > > > some
> > > > > > > way, would break the greatest percentage of users.  I'm not
> sure
> > > how
> > > > > > others
> > > > > > > feel, but I tend to think of "breaking change" in that more
> fuzzy
> > > > > > fashion.
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
> > > > > jbmusso@gmail.com>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > Related - have you considered using semantic versioning [1]
> > > > > > > > (major.minor.patch)? Roughly, semver states that breaking
> > changes
> > > > > > > > should bump major, new backward-compatible features should
> bump
> > > > minor
> > > > > > > > while bug fixes should bump patch. It also supports
> pre-release
> > > > > > > > version (-alpha, -incubating or -whatever suffixes).
> > > > > > > >
> > > > > > > > In order to avoid having the first digit (major) being bumped
> > too
> > > > > > > > often (TP3 shall remain TP3!), a variation could be:
> > > > > > > > marketing.major.minor.patch (downside to that is 4 digits
> > > > versioning
> > > > > > > > instead of 3). For example, adding a new Gremlin step would
> > bump
> > > > > minor
> > > > > > > > while changing a step signature in a backward-incompatible
> > manner
> > > > > > > > would bump major.
> > > > > > > >
> > > > > > > > semver is very popular in the JavaScript/Node.js world and
> used
> > > > > > > > extensively with npm (node package manager).
> > > > > > > >
> > > > > > > > Just some thoughts.
> > > > > > > >
> > > > > > > > Jean-Baptiste
> > > > > > > >
> > > > > > > > [1] http://semver.org/
> > > > > > > >
> > > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> > > > > > spmallette@gmail.com>
> > > > > > > > wrote:
> > > > > > > > > I think it's worthwhile for us to do something we've not
> > really
> > > > > done
> > > > > > > > before
> > > > > > > > > with any of the TinkerPop projects: use branches. We
> > typically
> > > > tend
> > > > > > to
> > > > > > > > use
> > > > > > > > > branches for major refactoring that we might throw out, but
> > not
> > > > > > really
> > > > > > > > for
> > > > > > > > > release management. As we look past release 3.0.0, I think
> we
> > > > will
> > > > > > want
> > > > > > > > to
> > > > > > > > > have the capability to do more frequent minor releases
> (e.g.
> > > > 3.0.1,
> > > > > > > > 3.0.2,
> > > > > > > > > etc) while still being able to do work for a future 3.1.x
> > line
> > > of
> > > > > > code.
> > > > > > > > >
> > > > > > > > > I think we can do this without too much change if we
> > introduce
> > > a
> > > > > > simple
> > > > > > > > > branch system.  Release branch rules would be simple - we
> > > create
> > > > a
> > > > > > new
> > > > > > > > > branch from master called tp31 for the 3.1.x line of code.
> > Any
> > > > > > changes
> > > > > > > > > that are "breaking", introduce significant risk, a "major"
> > > > feature,
> > > > > > > etc.
> > > > > > > > > would be committed there.  All other changes, bug fixes,
> > > > > non-breaking
> > > > > > > > > refactoring of major APIs, "minor" features, etc. would
> > simply
> > > > > commit
> > > > > > > to
> > > > > > > > > master.  the master branch effectively becomes the 3.0.x
> line
> > > of
> > > > > > code.
> > > > > > > > > Under this approach the merge process is pretty simple in
> > that
> > > we
> > > > > > just
> > > > > > > > > merge forward (i.e. master merges to to tp31).
> > > > > > > > >
> > > > > > > > > When the day comes that we're ready to release 3.1.0, we
> > merge
> > > > tp31
> > > > > > > back
> > > > > > > > to
> > > > > > > > > master and create tp32 and use the same model where the
> 3.1.x
> > > > line
> > > > > is
> > > > > > > > > master and the 3.2.x line is tp32.  Of course, under this
> > model
> > > > we
> > > > > > are
> > > > > > > > > really supporting just the previous minor version, which
> for
> > > > right
> > > > > > now
> > > > > > > > > seems acceptable to me.  That's more than what we've ever
> > > really
> > > > > done
> > > > > > > > well,
> > > > > > > > > so that feels like a good starting point in my book.  After
> > we
> > > > > > release
> > > > > > > > > 3.1.0 we can revisit and decide if a more complex branching
> > > > > strategy
> > > > > > is
> > > > > > > > > needed.
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

Are you suggesting that on release we rectify the JIRA report with the
CHANGELOG?  In that way, if something was done by way of JIRA we wouldn't
have to enter a CHANGELOG entry manually, because on release we'd pick it
up via the JIRA report?

On Thu, Jul 23, 2015 at 1:28 PM, Matt Frantz <ma...@gmail.com>
wrote:

> Perhaps in the release process we could generate a JIRA report of issues
> marked as fixed in the specific version, and reserve the CHANGELOG for
> significant changes and things that were not tracked through JIRA.
>
> On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > We have typically treated CHANGELOG rather unscientifically.  Make a
> change
> > of significance, then update the changelog for the appropriate version.
> I
> > bat around the idea of including the issue ids all the time but haven't
> > wanted to start the trend of doing that.  Perhaps we do that and make it
> > optional?? Not sure how others feel on that matter.
> >
> > On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <
> matthew.h.frantz@gmail.com>
> > wrote:
> >
> > > I just merged my fix for TINKERPOP3-782 to both tp30 and master.  I
> > didn't
> > > touch CHANGELOG.  Do we do that for every bug fix?  I don't see
> > references
> > > to JIRA artifacts in the CHANGELOG.
> > >
> > > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <
> spmallette@gmail.com>
> > > wrote:
> > >
> > > > Hi Matt,
> > > >
> > > > I have a PR currently targeted at tp30 (because it is a low-risk bug
> > > fix).
> > > > > I know that we don't necessarily code review everything that goes
> in,
> > > but
> > > > > since I'm relatively new, I wouldn't mind someone taking a peek at
> > it,
> > > > and
> > > > > the verify that tp30 is the best target.
> > > > >
> > > >
> > > > Right - no official code review.  We pretty much tend to handle it as
> > you
> > > > just did - on a case-by-case basis.
> > > >
> > > >
> > > > > (I don't have permissions on the GitHub mirror for
> > > incubating-tinkerpop.
> > > > > Should I?)
> > > > >
> > > >
> > > > I don't think you should - I don't have permissions either.
> > > >
> > > >
> > > > > Also, after it is merged to tp30, is the process going to be that I
> > > would
> > > > > also need to merge tp30 into master?  Or do we plan to merge only
> > > > > occasionally?
> > > >
> > > >
> > > > I've been the only person committing things to tp30 of any substance
> so
> > > > I've been doing it periodically, but generally speaking, I'd say that
> > > it's
> > > > best if the person who commits to tp30 merges to master (unless it's
> > > > something pretty trivial).  In that way the person who committed to
> > tp30
> > > is
> > > > responsible for ensuring proper integration with master.
> > > >
> > > >
> > > >
> > > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> > > matthew.h.frantz@gmail.com>
> > > > wrote:
> > > >
> > > > > I have a PR currently targeted at tp30 (because it is a low-risk
> bug
> > > > fix).
> > > > > I know that we don't necessarily code review everything that goes
> in,
> > > but
> > > > > since I'm relatively new, I wouldn't mind someone taking a peek at
> > it,
> > > > and
> > > > > the verify that tp30 is the best target.
> > > > >
> > > > > (I don't have permissions on the GitHub mirror for
> > > incubating-tinkerpop.
> > > > > Should I?)
> > > > >
> > > > > Also, after it is merged to tp30, is the process going to be that I
> > > would
> > > > > also need to merge tp30 into master?  Or do we plan to merge only
> > > > > occasionally?
> > > > >
> > > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> > > spmallette@gmail.com>
> > > > > wrote:
> > > > >
> > > > > > Thanks JB - i'm familiar with semver and I think the idea is to
> > > follow
> > > > it
> > > > > > in principle, in that we will save API breaking change for the
> > > "minor"
> > > > > > version.   imo, we should stick to the three digit system for now
> > > but I
> > > > > > guess it's worth considering what a "breaking change" is in our
> > > > context.
> > > > > >
> > > > > > TinkerPop is "big" - it has both public and internal APIs.  if i
> > > change
> > > > > the
> > > > > > package name of an internal API in a patch release, I wouldn't
> > expect
> > > > > that
> > > > > > to break anyone and thus I'm not sure I'd consider that a
> breaking
> > > > change
> > > > > >  (though it's always interesting to see how folks find their way
> > into
> > > > > using
> > > > > > our internal classes) .  To me the "breaking changes" are ones
> that
> > > > occur
> > > > > > in the public classes (i.e. the ones people are likely to use)
> > like:
> > > > > > gremlin driver classes, structure API for vendors, step classes
> and
> > > > > > GraphTraversal/GraphTraversalSource, etc. Changing those classes
> in
> > > > some
> > > > > > way, would break the greatest percentage of users.  I'm not sure
> > how
> > > > > others
> > > > > > feel, but I tend to think of "breaking change" in that more fuzzy
> > > > > fashion.
> > > > > >
> > > > > >
> > > > > >
> > > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
> > > > jbmusso@gmail.com>
> > > > > > wrote:
> > > > > >
> > > > > > > Related - have you considered using semantic versioning [1]
> > > > > > > (major.minor.patch)? Roughly, semver states that breaking
> changes
> > > > > > > should bump major, new backward-compatible features should bump
> > > minor
> > > > > > > while bug fixes should bump patch. It also supports pre-release
> > > > > > > version (-alpha, -incubating or -whatever suffixes).
> > > > > > >
> > > > > > > In order to avoid having the first digit (major) being bumped
> too
> > > > > > > often (TP3 shall remain TP3!), a variation could be:
> > > > > > > marketing.major.minor.patch (downside to that is 4 digits
> > > versioning
> > > > > > > instead of 3). For example, adding a new Gremlin step would
> bump
> > > > minor
> > > > > > > while changing a step signature in a backward-incompatible
> manner
> > > > > > > would bump major.
> > > > > > >
> > > > > > > semver is very popular in the JavaScript/Node.js world and used
> > > > > > > extensively with npm (node package manager).
> > > > > > >
> > > > > > > Just some thoughts.
> > > > > > >
> > > > > > > Jean-Baptiste
> > > > > > >
> > > > > > > [1] http://semver.org/
> > > > > > >
> > > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> > > > > spmallette@gmail.com>
> > > > > > > wrote:
> > > > > > > > I think it's worthwhile for us to do something we've not
> really
> > > > done
> > > > > > > before
> > > > > > > > with any of the TinkerPop projects: use branches. We
> typically
> > > tend
> > > > > to
> > > > > > > use
> > > > > > > > branches for major refactoring that we might throw out, but
> not
> > > > > really
> > > > > > > for
> > > > > > > > release management. As we look past release 3.0.0, I think we
> > > will
> > > > > want
> > > > > > > to
> > > > > > > > have the capability to do more frequent minor releases (e.g.
> > > 3.0.1,
> > > > > > > 3.0.2,
> > > > > > > > etc) while still being able to do work for a future 3.1.x
> line
> > of
> > > > > code.
> > > > > > > >
> > > > > > > > I think we can do this without too much change if we
> introduce
> > a
> > > > > simple
> > > > > > > > branch system.  Release branch rules would be simple - we
> > create
> > > a
> > > > > new
> > > > > > > > branch from master called tp31 for the 3.1.x line of code.
> Any
> > > > > changes
> > > > > > > > that are "breaking", introduce significant risk, a "major"
> > > feature,
> > > > > > etc.
> > > > > > > > would be committed there.  All other changes, bug fixes,
> > > > non-breaking
> > > > > > > > refactoring of major APIs, "minor" features, etc. would
> simply
> > > > commit
> > > > > > to
> > > > > > > > master.  the master branch effectively becomes the 3.0.x line
> > of
> > > > > code.
> > > > > > > > Under this approach the merge process is pretty simple in
> that
> > we
> > > > > just
> > > > > > > > merge forward (i.e. master merges to to tp31).
> > > > > > > >
> > > > > > > > When the day comes that we're ready to release 3.1.0, we
> merge
> > > tp31
> > > > > > back
> > > > > > > to
> > > > > > > > master and create tp32 and use the same model where the 3.1.x
> > > line
> > > > is
> > > > > > > > master and the 3.2.x line is tp32.  Of course, under this
> model
> > > we
> > > > > are
> > > > > > > > really supporting just the previous minor version, which for
> > > right
> > > > > now
> > > > > > > > seems acceptable to me.  That's more than what we've ever
> > really
> > > > done
> > > > > > > well,
> > > > > > > > so that feels like a good starting point in my book.  After
> we
> > > > > release
> > > > > > > > 3.1.0 we can revisit and decide if a more complex branching
> > > > strategy
> > > > > is
> > > > > > > > needed.
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

Re: branching after GA

[Matt Frantz <ma...@gmail.com>]

Perhaps in the release process we could generate a JIRA report of issues
marked as fixed in the specific version, and reserve the CHANGELOG for
significant changes and things that were not tracked through JIRA.

On Thu, Jul 23, 2015 at 9:41 AM, Stephen Mallette <sp...@gmail.com>
wrote:

> We have typically treated CHANGELOG rather unscientifically.  Make a change
> of significance, then update the changelog for the appropriate version.  I
> bat around the idea of including the issue ids all the time but haven't
> wanted to start the trend of doing that.  Perhaps we do that and make it
> optional?? Not sure how others feel on that matter.
>
> On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <ma...@gmail.com>
> wrote:
>
> > I just merged my fix for TINKERPOP3-782 to both tp30 and master.  I
> didn't
> > touch CHANGELOG.  Do we do that for every bug fix?  I don't see
> references
> > to JIRA artifacts in the CHANGELOG.
> >
> > On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> >
> > > Hi Matt,
> > >
> > > I have a PR currently targeted at tp30 (because it is a low-risk bug
> > fix).
> > > > I know that we don't necessarily code review everything that goes in,
> > but
> > > > since I'm relatively new, I wouldn't mind someone taking a peek at
> it,
> > > and
> > > > the verify that tp30 is the best target.
> > > >
> > >
> > > Right - no official code review.  We pretty much tend to handle it as
> you
> > > just did - on a case-by-case basis.
> > >
> > >
> > > > (I don't have permissions on the GitHub mirror for
> > incubating-tinkerpop.
> > > > Should I?)
> > > >
> > >
> > > I don't think you should - I don't have permissions either.
> > >
> > >
> > > > Also, after it is merged to tp30, is the process going to be that I
> > would
> > > > also need to merge tp30 into master?  Or do we plan to merge only
> > > > occasionally?
> > >
> > >
> > > I've been the only person committing things to tp30 of any substance so
> > > I've been doing it periodically, but generally speaking, I'd say that
> > it's
> > > best if the person who commits to tp30 merges to master (unless it's
> > > something pretty trivial).  In that way the person who committed to
> tp30
> > is
> > > responsible for ensuring proper integration with master.
> > >
> > >
> > >
> > > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> > matthew.h.frantz@gmail.com>
> > > wrote:
> > >
> > > > I have a PR currently targeted at tp30 (because it is a low-risk bug
> > > fix).
> > > > I know that we don't necessarily code review everything that goes in,
> > but
> > > > since I'm relatively new, I wouldn't mind someone taking a peek at
> it,
> > > and
> > > > the verify that tp30 is the best target.
> > > >
> > > > (I don't have permissions on the GitHub mirror for
> > incubating-tinkerpop.
> > > > Should I?)
> > > >
> > > > Also, after it is merged to tp30, is the process going to be that I
> > would
> > > > also need to merge tp30 into master?  Or do we plan to merge only
> > > > occasionally?
> > > >
> > > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> > spmallette@gmail.com>
> > > > wrote:
> > > >
> > > > > Thanks JB - i'm familiar with semver and I think the idea is to
> > follow
> > > it
> > > > > in principle, in that we will save API breaking change for the
> > "minor"
> > > > > version.   imo, we should stick to the three digit system for now
> > but I
> > > > > guess it's worth considering what a "breaking change" is in our
> > > context.
> > > > >
> > > > > TinkerPop is "big" - it has both public and internal APIs.  if i
> > change
> > > > the
> > > > > package name of an internal API in a patch release, I wouldn't
> expect
> > > > that
> > > > > to break anyone and thus I'm not sure I'd consider that a breaking
> > > change
> > > > >  (though it's always interesting to see how folks find their way
> into
> > > > using
> > > > > our internal classes) .  To me the "breaking changes" are ones that
> > > occur
> > > > > in the public classes (i.e. the ones people are likely to use)
> like:
> > > > > gremlin driver classes, structure API for vendors, step classes and
> > > > > GraphTraversal/GraphTraversalSource, etc. Changing those classes in
> > > some
> > > > > way, would break the greatest percentage of users.  I'm not sure
> how
> > > > others
> > > > > feel, but I tend to think of "breaking change" in that more fuzzy
> > > > fashion.
> > > > >
> > > > >
> > > > >
> > > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
> > > jbmusso@gmail.com>
> > > > > wrote:
> > > > >
> > > > > > Related - have you considered using semantic versioning [1]
> > > > > > (major.minor.patch)? Roughly, semver states that breaking changes
> > > > > > should bump major, new backward-compatible features should bump
> > minor
> > > > > > while bug fixes should bump patch. It also supports pre-release
> > > > > > version (-alpha, -incubating or -whatever suffixes).
> > > > > >
> > > > > > In order to avoid having the first digit (major) being bumped too
> > > > > > often (TP3 shall remain TP3!), a variation could be:
> > > > > > marketing.major.minor.patch (downside to that is 4 digits
> > versioning
> > > > > > instead of 3). For example, adding a new Gremlin step would bump
> > > minor
> > > > > > while changing a step signature in a backward-incompatible manner
> > > > > > would bump major.
> > > > > >
> > > > > > semver is very popular in the JavaScript/Node.js world and used
> > > > > > extensively with npm (node package manager).
> > > > > >
> > > > > > Just some thoughts.
> > > > > >
> > > > > > Jean-Baptiste
> > > > > >
> > > > > > [1] http://semver.org/
> > > > > >
> > > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> > > > spmallette@gmail.com>
> > > > > > wrote:
> > > > > > > I think it's worthwhile for us to do something we've not really
> > > done
> > > > > > before
> > > > > > > with any of the TinkerPop projects: use branches. We typically
> > tend
> > > > to
> > > > > > use
> > > > > > > branches for major refactoring that we might throw out, but not
> > > > really
> > > > > > for
> > > > > > > release management. As we look past release 3.0.0, I think we
> > will
> > > > want
> > > > > > to
> > > > > > > have the capability to do more frequent minor releases (e.g.
> > 3.0.1,
> > > > > > 3.0.2,
> > > > > > > etc) while still being able to do work for a future 3.1.x line
> of
> > > > code.
> > > > > > >
> > > > > > > I think we can do this without too much change if we introduce
> a
> > > > simple
> > > > > > > branch system.  Release branch rules would be simple - we
> create
> > a
> > > > new
> > > > > > > branch from master called tp31 for the 3.1.x line of code.  Any
> > > > changes
> > > > > > > that are "breaking", introduce significant risk, a "major"
> > feature,
> > > > > etc.
> > > > > > > would be committed there.  All other changes, bug fixes,
> > > non-breaking
> > > > > > > refactoring of major APIs, "minor" features, etc. would simply
> > > commit
> > > > > to
> > > > > > > master.  the master branch effectively becomes the 3.0.x line
> of
> > > > code.
> > > > > > > Under this approach the merge process is pretty simple in that
> we
> > > > just
> > > > > > > merge forward (i.e. master merges to to tp31).
> > > > > > >
> > > > > > > When the day comes that we're ready to release 3.1.0, we merge
> > tp31
> > > > > back
> > > > > > to
> > > > > > > master and create tp32 and use the same model where the 3.1.x
> > line
> > > is
> > > > > > > master and the 3.2.x line is tp32.  Of course, under this model
> > we
> > > > are
> > > > > > > really supporting just the previous minor version, which for
> > right
> > > > now
> > > > > > > seems acceptable to me.  That's more than what we've ever
> really
> > > done
> > > > > > well,
> > > > > > > so that feels like a good starting point in my book.  After we
> > > > release
> > > > > > > 3.1.0 we can revisit and decide if a more complex branching
> > > strategy
> > > > is
> > > > > > > needed.
> > > > > >
> > > > >
> > > >
> > >
> >
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

We have typically treated CHANGELOG rather unscientifically.  Make a change
of significance, then update the changelog for the appropriate version.  I
bat around the idea of including the issue ids all the time but haven't
wanted to start the trend of doing that.  Perhaps we do that and make it
optional?? Not sure how others feel on that matter.

On Thu, Jul 23, 2015 at 11:35 AM, Matt Frantz <ma...@gmail.com>
wrote:

> I just merged my fix for TINKERPOP3-782 to both tp30 and master.  I didn't
> touch CHANGELOG.  Do we do that for every bug fix?  I don't see references
> to JIRA artifacts in the CHANGELOG.
>
> On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > Hi Matt,
> >
> > I have a PR currently targeted at tp30 (because it is a low-risk bug
> fix).
> > > I know that we don't necessarily code review everything that goes in,
> but
> > > since I'm relatively new, I wouldn't mind someone taking a peek at it,
> > and
> > > the verify that tp30 is the best target.
> > >
> >
> > Right - no official code review.  We pretty much tend to handle it as you
> > just did - on a case-by-case basis.
> >
> >
> > > (I don't have permissions on the GitHub mirror for
> incubating-tinkerpop.
> > > Should I?)
> > >
> >
> > I don't think you should - I don't have permissions either.
> >
> >
> > > Also, after it is merged to tp30, is the process going to be that I
> would
> > > also need to merge tp30 into master?  Or do we plan to merge only
> > > occasionally?
> >
> >
> > I've been the only person committing things to tp30 of any substance so
> > I've been doing it periodically, but generally speaking, I'd say that
> it's
> > best if the person who commits to tp30 merges to master (unless it's
> > something pretty trivial).  In that way the person who committed to tp30
> is
> > responsible for ensuring proper integration with master.
> >
> >
> >
> > On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <
> matthew.h.frantz@gmail.com>
> > wrote:
> >
> > > I have a PR currently targeted at tp30 (because it is a low-risk bug
> > fix).
> > > I know that we don't necessarily code review everything that goes in,
> but
> > > since I'm relatively new, I wouldn't mind someone taking a peek at it,
> > and
> > > the verify that tp30 is the best target.
> > >
> > > (I don't have permissions on the GitHub mirror for
> incubating-tinkerpop.
> > > Should I?)
> > >
> > > Also, after it is merged to tp30, is the process going to be that I
> would
> > > also need to merge tp30 into master?  Or do we plan to merge only
> > > occasionally?
> > >
> > > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <
> spmallette@gmail.com>
> > > wrote:
> > >
> > > > Thanks JB - i'm familiar with semver and I think the idea is to
> follow
> > it
> > > > in principle, in that we will save API breaking change for the
> "minor"
> > > > version.   imo, we should stick to the three digit system for now
> but I
> > > > guess it's worth considering what a "breaking change" is in our
> > context.
> > > >
> > > > TinkerPop is "big" - it has both public and internal APIs.  if i
> change
> > > the
> > > > package name of an internal API in a patch release, I wouldn't expect
> > > that
> > > > to break anyone and thus I'm not sure I'd consider that a breaking
> > change
> > > >  (though it's always interesting to see how folks find their way into
> > > using
> > > > our internal classes) .  To me the "breaking changes" are ones that
> > occur
> > > > in the public classes (i.e. the ones people are likely to use) like:
> > > > gremlin driver classes, structure API for vendors, step classes and
> > > > GraphTraversal/GraphTraversalSource, etc. Changing those classes in
> > some
> > > > way, would break the greatest percentage of users.  I'm not sure how
> > > others
> > > > feel, but I tend to think of "breaking change" in that more fuzzy
> > > fashion.
> > > >
> > > >
> > > >
> > > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
> > jbmusso@gmail.com>
> > > > wrote:
> > > >
> > > > > Related - have you considered using semantic versioning [1]
> > > > > (major.minor.patch)? Roughly, semver states that breaking changes
> > > > > should bump major, new backward-compatible features should bump
> minor
> > > > > while bug fixes should bump patch. It also supports pre-release
> > > > > version (-alpha, -incubating or -whatever suffixes).
> > > > >
> > > > > In order to avoid having the first digit (major) being bumped too
> > > > > often (TP3 shall remain TP3!), a variation could be:
> > > > > marketing.major.minor.patch (downside to that is 4 digits
> versioning
> > > > > instead of 3). For example, adding a new Gremlin step would bump
> > minor
> > > > > while changing a step signature in a backward-incompatible manner
> > > > > would bump major.
> > > > >
> > > > > semver is very popular in the JavaScript/Node.js world and used
> > > > > extensively with npm (node package manager).
> > > > >
> > > > > Just some thoughts.
> > > > >
> > > > > Jean-Baptiste
> > > > >
> > > > > [1] http://semver.org/
> > > > >
> > > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> > > spmallette@gmail.com>
> > > > > wrote:
> > > > > > I think it's worthwhile for us to do something we've not really
> > done
> > > > > before
> > > > > > with any of the TinkerPop projects: use branches. We typically
> tend
> > > to
> > > > > use
> > > > > > branches for major refactoring that we might throw out, but not
> > > really
> > > > > for
> > > > > > release management. As we look past release 3.0.0, I think we
> will
> > > want
> > > > > to
> > > > > > have the capability to do more frequent minor releases (e.g.
> 3.0.1,
> > > > > 3.0.2,
> > > > > > etc) while still being able to do work for a future 3.1.x line of
> > > code.
> > > > > >
> > > > > > I think we can do this without too much change if we introduce a
> > > simple
> > > > > > branch system.  Release branch rules would be simple - we create
> a
> > > new
> > > > > > branch from master called tp31 for the 3.1.x line of code.  Any
> > > changes
> > > > > > that are "breaking", introduce significant risk, a "major"
> feature,
> > > > etc.
> > > > > > would be committed there.  All other changes, bug fixes,
> > non-breaking
> > > > > > refactoring of major APIs, "minor" features, etc. would simply
> > commit
> > > > to
> > > > > > master.  the master branch effectively becomes the 3.0.x line of
> > > code.
> > > > > > Under this approach the merge process is pretty simple in that we
> > > just
> > > > > > merge forward (i.e. master merges to to tp31).
> > > > > >
> > > > > > When the day comes that we're ready to release 3.1.0, we merge
> tp31
> > > > back
> > > > > to
> > > > > > master and create tp32 and use the same model where the 3.1.x
> line
> > is
> > > > > > master and the 3.2.x line is tp32.  Of course, under this model
> we
> > > are
> > > > > > really supporting just the previous minor version, which for
> right
> > > now
> > > > > > seems acceptable to me.  That's more than what we've ever really
> > done
> > > > > well,
> > > > > > so that feels like a good starting point in my book.  After we
> > > release
> > > > > > 3.1.0 we can revisit and decide if a more complex branching
> > strategy
> > > is
> > > > > > needed.
> > > > >
> > > >
> > >
> >
>

Re: branching after GA

[Matt Frantz <ma...@gmail.com>]

I just merged my fix for TINKERPOP3-782 to both tp30 and master.  I didn't
touch CHANGELOG.  Do we do that for every bug fix?  I don't see references
to JIRA artifacts in the CHANGELOG.

On Thu, Jul 23, 2015 at 3:59 AM, Stephen Mallette <sp...@gmail.com>
wrote:

> Hi Matt,
>
> I have a PR currently targeted at tp30 (because it is a low-risk bug fix).
> > I know that we don't necessarily code review everything that goes in, but
> > since I'm relatively new, I wouldn't mind someone taking a peek at it,
> and
> > the verify that tp30 is the best target.
> >
>
> Right - no official code review.  We pretty much tend to handle it as you
> just did - on a case-by-case basis.
>
>
> > (I don't have permissions on the GitHub mirror for incubating-tinkerpop.
> > Should I?)
> >
>
> I don't think you should - I don't have permissions either.
>
>
> > Also, after it is merged to tp30, is the process going to be that I would
> > also need to merge tp30 into master?  Or do we plan to merge only
> > occasionally?
>
>
> I've been the only person committing things to tp30 of any substance so
> I've been doing it periodically, but generally speaking, I'd say that it's
> best if the person who commits to tp30 merges to master (unless it's
> something pretty trivial).  In that way the person who committed to tp30 is
> responsible for ensuring proper integration with master.
>
>
>
> On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <ma...@gmail.com>
> wrote:
>
> > I have a PR currently targeted at tp30 (because it is a low-risk bug
> fix).
> > I know that we don't necessarily code review everything that goes in, but
> > since I'm relatively new, I wouldn't mind someone taking a peek at it,
> and
> > the verify that tp30 is the best target.
> >
> > (I don't have permissions on the GitHub mirror for incubating-tinkerpop.
> > Should I?)
> >
> > Also, after it is merged to tp30, is the process going to be that I would
> > also need to merge tp30 into master?  Or do we plan to merge only
> > occasionally?
> >
> > On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> >
> > > Thanks JB - i'm familiar with semver and I think the idea is to follow
> it
> > > in principle, in that we will save API breaking change for the "minor"
> > > version.   imo, we should stick to the three digit system for now but I
> > > guess it's worth considering what a "breaking change" is in our
> context.
> > >
> > > TinkerPop is "big" - it has both public and internal APIs.  if i change
> > the
> > > package name of an internal API in a patch release, I wouldn't expect
> > that
> > > to break anyone and thus I'm not sure I'd consider that a breaking
> change
> > >  (though it's always interesting to see how folks find their way into
> > using
> > > our internal classes) .  To me the "breaking changes" are ones that
> occur
> > > in the public classes (i.e. the ones people are likely to use) like:
> > > gremlin driver classes, structure API for vendors, step classes and
> > > GraphTraversal/GraphTraversalSource, etc. Changing those classes in
> some
> > > way, would break the greatest percentage of users.  I'm not sure how
> > others
> > > feel, but I tend to think of "breaking change" in that more fuzzy
> > fashion.
> > >
> > >
> > >
> > > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <
> jbmusso@gmail.com>
> > > wrote:
> > >
> > > > Related - have you considered using semantic versioning [1]
> > > > (major.minor.patch)? Roughly, semver states that breaking changes
> > > > should bump major, new backward-compatible features should bump minor
> > > > while bug fixes should bump patch. It also supports pre-release
> > > > version (-alpha, -incubating or -whatever suffixes).
> > > >
> > > > In order to avoid having the first digit (major) being bumped too
> > > > often (TP3 shall remain TP3!), a variation could be:
> > > > marketing.major.minor.patch (downside to that is 4 digits versioning
> > > > instead of 3). For example, adding a new Gremlin step would bump
> minor
> > > > while changing a step signature in a backward-incompatible manner
> > > > would bump major.
> > > >
> > > > semver is very popular in the JavaScript/Node.js world and used
> > > > extensively with npm (node package manager).
> > > >
> > > > Just some thoughts.
> > > >
> > > > Jean-Baptiste
> > > >
> > > > [1] http://semver.org/
> > > >
> > > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> > spmallette@gmail.com>
> > > > wrote:
> > > > > I think it's worthwhile for us to do something we've not really
> done
> > > > before
> > > > > with any of the TinkerPop projects: use branches. We typically tend
> > to
> > > > use
> > > > > branches for major refactoring that we might throw out, but not
> > really
> > > > for
> > > > > release management. As we look past release 3.0.0, I think we will
> > want
> > > > to
> > > > > have the capability to do more frequent minor releases (e.g. 3.0.1,
> > > > 3.0.2,
> > > > > etc) while still being able to do work for a future 3.1.x line of
> > code.
> > > > >
> > > > > I think we can do this without too much change if we introduce a
> > simple
> > > > > branch system.  Release branch rules would be simple - we create a
> > new
> > > > > branch from master called tp31 for the 3.1.x line of code.  Any
> > changes
> > > > > that are "breaking", introduce significant risk, a "major" feature,
> > > etc.
> > > > > would be committed there.  All other changes, bug fixes,
> non-breaking
> > > > > refactoring of major APIs, "minor" features, etc. would simply
> commit
> > > to
> > > > > master.  the master branch effectively becomes the 3.0.x line of
> > code.
> > > > > Under this approach the merge process is pretty simple in that we
> > just
> > > > > merge forward (i.e. master merges to to tp31).
> > > > >
> > > > > When the day comes that we're ready to release 3.1.0, we merge tp31
> > > back
> > > > to
> > > > > master and create tp32 and use the same model where the 3.1.x line
> is
> > > > > master and the 3.2.x line is tp32.  Of course, under this model we
> > are
> > > > > really supporting just the previous minor version, which for right
> > now
> > > > > seems acceptable to me.  That's more than what we've ever really
> done
> > > > well,
> > > > > so that feels like a good starting point in my book.  After we
> > release
> > > > > 3.1.0 we can revisit and decide if a more complex branching
> strategy
> > is
> > > > > needed.
> > > >
> > >
> >
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

Hi Matt,

I have a PR currently targeted at tp30 (because it is a low-risk bug fix).
> I know that we don't necessarily code review everything that goes in, but
> since I'm relatively new, I wouldn't mind someone taking a peek at it, and
> the verify that tp30 is the best target.
>

Right - no official code review.  We pretty much tend to handle it as you
just did - on a case-by-case basis.


> (I don't have permissions on the GitHub mirror for incubating-tinkerpop.
> Should I?)
>

I don't think you should - I don't have permissions either.


> Also, after it is merged to tp30, is the process going to be that I would
> also need to merge tp30 into master?  Or do we plan to merge only
> occasionally?


I've been the only person committing things to tp30 of any substance so
I've been doing it periodically, but generally speaking, I'd say that it's
best if the person who commits to tp30 merges to master (unless it's
something pretty trivial).  In that way the person who committed to tp30 is
responsible for ensuring proper integration with master.



On Thu, Jul 23, 2015 at 12:19 AM, Matt Frantz <ma...@gmail.com>
wrote:

> I have a PR currently targeted at tp30 (because it is a low-risk bug fix).
> I know that we don't necessarily code review everything that goes in, but
> since I'm relatively new, I wouldn't mind someone taking a peek at it, and
> the verify that tp30 is the best target.
>
> (I don't have permissions on the GitHub mirror for incubating-tinkerpop.
> Should I?)
>
> Also, after it is merged to tp30, is the process going to be that I would
> also need to merge tp30 into master?  Or do we plan to merge only
> occasionally?
>
> On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <sp...@gmail.com>
> wrote:
>
> > Thanks JB - i'm familiar with semver and I think the idea is to follow it
> > in principle, in that we will save API breaking change for the "minor"
> > version.   imo, we should stick to the three digit system for now but I
> > guess it's worth considering what a "breaking change" is in our context.
> >
> > TinkerPop is "big" - it has both public and internal APIs.  if i change
> the
> > package name of an internal API in a patch release, I wouldn't expect
> that
> > to break anyone and thus I'm not sure I'd consider that a breaking change
> >  (though it's always interesting to see how folks find their way into
> using
> > our internal classes) .  To me the "breaking changes" are ones that occur
> > in the public classes (i.e. the ones people are likely to use) like:
> > gremlin driver classes, structure API for vendors, step classes and
> > GraphTraversal/GraphTraversalSource, etc. Changing those classes in some
> > way, would break the greatest percentage of users.  I'm not sure how
> others
> > feel, but I tend to think of "breaking change" in that more fuzzy
> fashion.
> >
> >
> >
> > On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <jb...@gmail.com>
> > wrote:
> >
> > > Related - have you considered using semantic versioning [1]
> > > (major.minor.patch)? Roughly, semver states that breaking changes
> > > should bump major, new backward-compatible features should bump minor
> > > while bug fixes should bump patch. It also supports pre-release
> > > version (-alpha, -incubating or -whatever suffixes).
> > >
> > > In order to avoid having the first digit (major) being bumped too
> > > often (TP3 shall remain TP3!), a variation could be:
> > > marketing.major.minor.patch (downside to that is 4 digits versioning
> > > instead of 3). For example, adding a new Gremlin step would bump minor
> > > while changing a step signature in a backward-incompatible manner
> > > would bump major.
> > >
> > > semver is very popular in the JavaScript/Node.js world and used
> > > extensively with npm (node package manager).
> > >
> > > Just some thoughts.
> > >
> > > Jean-Baptiste
> > >
> > > [1] http://semver.org/
> > >
> > > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <
> spmallette@gmail.com>
> > > wrote:
> > > > I think it's worthwhile for us to do something we've not really done
> > > before
> > > > with any of the TinkerPop projects: use branches. We typically tend
> to
> > > use
> > > > branches for major refactoring that we might throw out, but not
> really
> > > for
> > > > release management. As we look past release 3.0.0, I think we will
> want
> > > to
> > > > have the capability to do more frequent minor releases (e.g. 3.0.1,
> > > 3.0.2,
> > > > etc) while still being able to do work for a future 3.1.x line of
> code.
> > > >
> > > > I think we can do this without too much change if we introduce a
> simple
> > > > branch system.  Release branch rules would be simple - we create a
> new
> > > > branch from master called tp31 for the 3.1.x line of code.  Any
> changes
> > > > that are "breaking", introduce significant risk, a "major" feature,
> > etc.
> > > > would be committed there.  All other changes, bug fixes, non-breaking
> > > > refactoring of major APIs, "minor" features, etc. would simply commit
> > to
> > > > master.  the master branch effectively becomes the 3.0.x line of
> code.
> > > > Under this approach the merge process is pretty simple in that we
> just
> > > > merge forward (i.e. master merges to to tp31).
> > > >
> > > > When the day comes that we're ready to release 3.1.0, we merge tp31
> > back
> > > to
> > > > master and create tp32 and use the same model where the 3.1.x line is
> > > > master and the 3.2.x line is tp32.  Of course, under this model we
> are
> > > > really supporting just the previous minor version, which for right
> now
> > > > seems acceptable to me.  That's more than what we've ever really done
> > > well,
> > > > so that feels like a good starting point in my book.  After we
> release
> > > > 3.1.0 we can revisit and decide if a more complex branching strategy
> is
> > > > needed.
> > >
> >
>

Re: branching after GA

[Matt Frantz <ma...@gmail.com>]

I have a PR currently targeted at tp30 (because it is a low-risk bug fix).
I know that we don't necessarily code review everything that goes in, but
since I'm relatively new, I wouldn't mind someone taking a peek at it, and
the verify that tp30 is the best target.

(I don't have permissions on the GitHub mirror for incubating-tinkerpop.
Should I?)

Also, after it is merged to tp30, is the process going to be that I would
also need to merge tp30 into master?  Or do we plan to merge only
occasionally?

On Wed, Jul 15, 2015 at 5:19 AM, Stephen Mallette <sp...@gmail.com>
wrote:

> Thanks JB - i'm familiar with semver and I think the idea is to follow it
> in principle, in that we will save API breaking change for the "minor"
> version.   imo, we should stick to the three digit system for now but I
> guess it's worth considering what a "breaking change" is in our context.
>
> TinkerPop is "big" - it has both public and internal APIs.  if i change the
> package name of an internal API in a patch release, I wouldn't expect that
> to break anyone and thus I'm not sure I'd consider that a breaking change
>  (though it's always interesting to see how folks find their way into using
> our internal classes) .  To me the "breaking changes" are ones that occur
> in the public classes (i.e. the ones people are likely to use) like:
> gremlin driver classes, structure API for vendors, step classes and
> GraphTraversal/GraphTraversalSource, etc. Changing those classes in some
> way, would break the greatest percentage of users.  I'm not sure how others
> feel, but I tend to think of "breaking change" in that more fuzzy fashion.
>
>
>
> On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <jb...@gmail.com>
> wrote:
>
> > Related - have you considered using semantic versioning [1]
> > (major.minor.patch)? Roughly, semver states that breaking changes
> > should bump major, new backward-compatible features should bump minor
> > while bug fixes should bump patch. It also supports pre-release
> > version (-alpha, -incubating or -whatever suffixes).
> >
> > In order to avoid having the first digit (major) being bumped too
> > often (TP3 shall remain TP3!), a variation could be:
> > marketing.major.minor.patch (downside to that is 4 digits versioning
> > instead of 3). For example, adding a new Gremlin step would bump minor
> > while changing a step signature in a backward-incompatible manner
> > would bump major.
> >
> > semver is very popular in the JavaScript/Node.js world and used
> > extensively with npm (node package manager).
> >
> > Just some thoughts.
> >
> > Jean-Baptiste
> >
> > [1] http://semver.org/
> >
> > On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <sp...@gmail.com>
> > wrote:
> > > I think it's worthwhile for us to do something we've not really done
> > before
> > > with any of the TinkerPop projects: use branches. We typically tend to
> > use
> > > branches for major refactoring that we might throw out, but not really
> > for
> > > release management. As we look past release 3.0.0, I think we will want
> > to
> > > have the capability to do more frequent minor releases (e.g. 3.0.1,
> > 3.0.2,
> > > etc) while still being able to do work for a future 3.1.x line of code.
> > >
> > > I think we can do this without too much change if we introduce a simple
> > > branch system.  Release branch rules would be simple - we create a new
> > > branch from master called tp31 for the 3.1.x line of code.  Any changes
> > > that are "breaking", introduce significant risk, a "major" feature,
> etc.
> > > would be committed there.  All other changes, bug fixes, non-breaking
> > > refactoring of major APIs, "minor" features, etc. would simply commit
> to
> > > master.  the master branch effectively becomes the 3.0.x line of code.
> > > Under this approach the merge process is pretty simple in that we just
> > > merge forward (i.e. master merges to to tp31).
> > >
> > > When the day comes that we're ready to release 3.1.0, we merge tp31
> back
> > to
> > > master and create tp32 and use the same model where the 3.1.x line is
> > > master and the 3.2.x line is tp32.  Of course, under this model we are
> > > really supporting just the previous minor version, which for right now
> > > seems acceptable to me.  That's more than what we've ever really done
> > well,
> > > so that feels like a good starting point in my book.  After we release
> > > 3.1.0 we can revisit and decide if a more complex branching strategy is
> > > needed.
> >
>

Re: branching after GA

[Stephen Mallette <sp...@gmail.com>]

Thanks JB - i'm familiar with semver and I think the idea is to follow it
in principle, in that we will save API breaking change for the "minor"
version.   imo, we should stick to the three digit system for now but I
guess it's worth considering what a "breaking change" is in our context.

TinkerPop is "big" - it has both public and internal APIs.  if i change the
package name of an internal API in a patch release, I wouldn't expect that
to break anyone and thus I'm not sure I'd consider that a breaking change
 (though it's always interesting to see how folks find their way into using
our internal classes) .  To me the "breaking changes" are ones that occur
in the public classes (i.e. the ones people are likely to use) like:
gremlin driver classes, structure API for vendors, step classes and
GraphTraversal/GraphTraversalSource, etc. Changing those classes in some
way, would break the greatest percentage of users.  I'm not sure how others
feel, but I tend to think of "breaking change" in that more fuzzy fashion.



On Wed, Jul 15, 2015 at 7:38 AM, Jean-Baptiste Musso <jb...@gmail.com>
wrote:

> Related - have you considered using semantic versioning [1]
> (major.minor.patch)? Roughly, semver states that breaking changes
> should bump major, new backward-compatible features should bump minor
> while bug fixes should bump patch. It also supports pre-release
> version (-alpha, -incubating or -whatever suffixes).
>
> In order to avoid having the first digit (major) being bumped too
> often (TP3 shall remain TP3!), a variation could be:
> marketing.major.minor.patch (downside to that is 4 digits versioning
> instead of 3). For example, adding a new Gremlin step would bump minor
> while changing a step signature in a backward-incompatible manner
> would bump major.
>
> semver is very popular in the JavaScript/Node.js world and used
> extensively with npm (node package manager).
>
> Just some thoughts.
>
> Jean-Baptiste
>
> [1] http://semver.org/
>
> On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <sp...@gmail.com>
> wrote:
> > I think it's worthwhile for us to do something we've not really done
> before
> > with any of the TinkerPop projects: use branches. We typically tend to
> use
> > branches for major refactoring that we might throw out, but not really
> for
> > release management. As we look past release 3.0.0, I think we will want
> to
> > have the capability to do more frequent minor releases (e.g. 3.0.1,
> 3.0.2,
> > etc) while still being able to do work for a future 3.1.x line of code.
> >
> > I think we can do this without too much change if we introduce a simple
> > branch system.  Release branch rules would be simple - we create a new
> > branch from master called tp31 for the 3.1.x line of code.  Any changes
> > that are "breaking", introduce significant risk, a "major" feature, etc.
> > would be committed there.  All other changes, bug fixes, non-breaking
> > refactoring of major APIs, "minor" features, etc. would simply commit to
> > master.  the master branch effectively becomes the 3.0.x line of code.
> > Under this approach the merge process is pretty simple in that we just
> > merge forward (i.e. master merges to to tp31).
> >
> > When the day comes that we're ready to release 3.1.0, we merge tp31 back
> to
> > master and create tp32 and use the same model where the 3.1.x line is
> > master and the 3.2.x line is tp32.  Of course, under this model we are
> > really supporting just the previous minor version, which for right now
> > seems acceptable to me.  That's more than what we've ever really done
> well,
> > so that feels like a good starting point in my book.  After we release
> > 3.1.0 we can revisit and decide if a more complex branching strategy is
> > needed.
>

Re: branching after GA

[Jean-Baptiste Musso <jb...@gmail.com>]

Related - have you considered using semantic versioning [1]
(major.minor.patch)? Roughly, semver states that breaking changes
should bump major, new backward-compatible features should bump minor
while bug fixes should bump patch. It also supports pre-release
version (-alpha, -incubating or -whatever suffixes).

In order to avoid having the first digit (major) being bumped too
often (TP3 shall remain TP3!), a variation could be:
marketing.major.minor.patch (downside to that is 4 digits versioning
instead of 3). For example, adding a new Gremlin step would bump minor
while changing a step signature in a backward-incompatible manner
would bump major.

semver is very popular in the JavaScript/Node.js world and used
extensively with npm (node package manager).

Just some thoughts.

Jean-Baptiste

[1] http://semver.org/

On Mon, Jul 13, 2015 at 1:20 PM, Stephen Mallette <sp...@gmail.com> wrote:
> I think it's worthwhile for us to do something we've not really done before
> with any of the TinkerPop projects: use branches. We typically tend to use
> branches for major refactoring that we might throw out, but not really for
> release management. As we look past release 3.0.0, I think we will want to
> have the capability to do more frequent minor releases (e.g. 3.0.1, 3.0.2,
> etc) while still being able to do work for a future 3.1.x line of code.
>
> I think we can do this without too much change if we introduce a simple
> branch system.  Release branch rules would be simple - we create a new
> branch from master called tp31 for the 3.1.x line of code.  Any changes
> that are "breaking", introduce significant risk, a "major" feature, etc.
> would be committed there.  All other changes, bug fixes, non-breaking
> refactoring of major APIs, "minor" features, etc. would simply commit to
> master.  the master branch effectively becomes the 3.0.x line of code.
> Under this approach the merge process is pretty simple in that we just
> merge forward (i.e. master merges to to tp31).
>
> When the day comes that we're ready to release 3.1.0, we merge tp31 back to
> master and create tp32 and use the same model where the 3.1.x line is
> master and the 3.2.x line is tp32.  Of course, under this model we are
> really supporting just the previous minor version, which for right now
> seems acceptable to me.  That's more than what we've ever really done well,
> so that feels like a good starting point in my book.  After we release
> 3.1.0 we can revisit and decide if a more complex branching strategy is
> needed.