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