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