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