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 <[email protected]> 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 <[email protected]> > wrote: > >> 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. >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>> >>>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>> >>>>>>>>> >>>>>>>> >>>>>>> >>>>>> >>>>>> >>>> >>> >>
