RFC here: https://github.com/apache/incubator-tinkerpop/pull/94
On Fri, Jul 31, 2015 at 3:02 AM, Stephen Mallette <[email protected]> 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 <[email protected]> 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 <[email protected]> > > 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 < > [email protected]> > > > 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 < > > [email protected]> > > >> 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 < > > [email protected]> > > >>> 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 < > > >>> [email protected]> > > >>> > 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 < > > >>> [email protected] > > >>> > > > > >>> > > 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 < > > >>> > [email protected] > > >>> > > > > > >>> > > > 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 < > > >>> > > [email protected]> > > >>> > > > > 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 < > > >>> > > > > [email protected]> > > >>> > > > > > 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 < > > >>> > > > > [email protected]> > > >>> > > >>> > > > > > > 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 < > > >>> > > > > > > [email protected]> > > >>> > > >>> > > > > > > > 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 < > > >>> > > > > > > [email protected]> > > >>> > > >>> > > > > > > > > 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 > > < > > >>> > > > > > > > [email protected]> > > >>> > > >>> > > > > > > > > > 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 < > > >>> > > > > > > > > [email protected]> > > >>> > > >>> > > > > > > > > > > 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. > > >>> > > > > > > > > > > > > >>> > > > > > > > > > > > >>> > > > > > > > > > > >>> > > > > > > > > > >>> > > > > > > > > >>> > > > > > > > >>> > > > > > > >>> > > > > > >>> > > > > >>> > > > >>> > > >> > > >> > > >
