That's looking good. I like how everything is separated for the different providers and users. Makes it quite easy to get the information we want.
On Thu, Oct 8, 2015 at 8:32 PM, Stephen Mallette <spmalle...@gmail.com> wrote: > yes - the "Upgrading" sections would be about migration. I was thinking > that each release would get a single standalone document which would take > you from the previous version forward...so if i was at 3.0.0 and going to > 3.0.1 then i just need the 3.0.1 release doc. If I was going from 3.0.0 to > 3.0.5 i would need the cumulative docs from 3.0.1 to 3.0.5. If i were > going from 3.0.0 to 3.1.0 i think we would roll up all the changes from > 3.0.x into the 3.1.0 release doc and then add in any additional change. > That's kinda what we've been doing with CHANGELOG thus far. > > On Thu, Oct 8, 2015 at 2:26 PM, Matt Frantz <matthew.h.fra...@gmail.com> > wrote: > > > The "Migration" information would be in the "Updating" section? > > > > How would we track the stack of migrations from version N to N+1 to N+2? > > Would it grow like a single CHANGELOG, or would there be separate > > documents? > > > > On Thu, Oct 8, 2015 at 9:47 AM, Stephen Mallette <spmalle...@gmail.com> > > wrote: > > > > > Since this idea was generally liked, I created a branch from tp30 to > play > > > around with the idea: > > > > > > https://github.com/apache/incubator-tinkerpop/tree/tp30-docs > > > > > > Unfortunately it meant mucking with the dreaded doc generation system > (so > > > there goes an easy 3.0.2 release for me), but, anyway, here's what I > did > > in > > > this branch for everyone to review: > > > > > > 1. I moved our asciidoc reference documentation to docs/src/book > > > 2. I created docs/src/article > > > 3. In "article" we can add our "release documents" > > > 4. An "article" doesn't have to be just for "release documents" - in > > > essence it can be anything, but I think it should be something time > > related > > > and static. > > > 5. Why static? because i don't expect an "article" to change. Like, it > > is > > > meant to be a snapshot of how something is at a point in time (note > that > > > Daniel's pre-processor isn't hooked up to this for this reason) > > > 6. This opens up the possibility that we could also have other > > directories > > > with generated content. The idea to have "dev" immediately came to > mind > > to > > > house "developer documentation". > > > > > > As for the format of our "release document" I did this: > > > > > > > > > > > > https://github.com/apache/incubator-tinkerpop/blob/tp30-docs/docs/src/article/09162015-release-3.0.1-incubating.asciidoc > > > > > > You can do a bin/process-docs.sh --dryRun to generate the doc - it will > > > show up in target/docs/htmlsingle/ as a standalone html file. I guess > > once > > > that html gets uploaded to the website, we can choose to link to that > > > document directly from wherever as a standalone file. > > > > > > What do you all think - both of overall change and the "release > document" > > > format? > > > > > > > > > > > > On Wed, Oct 7, 2015 at 12:01 PM, Jason Plurad <plur...@gmail.com> > wrote: > > > > > > > +1. As a consumer, I'd be more likely to read a "Migration" doc > before > > a > > > > Changelog. I'd only look at the Changelog if I were curious how they > > > > implemented the fix. With the Migration doc, I'd expect to learn how > to > > > > make my app work with the new version. > > > > > > > > On Wed, Oct 7, 2015 at 11:38 AM, Dylan Millikin < > > > dylan.milli...@gmail.com> > > > > wrote: > > > > > > > > > +1 I like the idea of a todo list of sorts. > > > > > > > > > > On Wed, Oct 7, 2015 at 5:18 PM, Marko Rodriguez < > > okramma...@gmail.com> > > > > > wrote: > > > > > > > > > > > Yes. This is a good idea. > > > > > > > > > > > > Marko. > > > > > > > > > > > > http://markorodriguez.com > > > > > > > > > > > > On Oct 7, 2015, at 8:55 AM, Matt Frantz < > > matthew.h.fra...@gmail.com> > > > > > > wrote: > > > > > > > > > > > > > I like the idea of creating "Migration" documents. Separate > docs > > > for > > > > > > > implementers and clients would probably make it easier to > > consume. > > > > > > > Refactoring the information as a "todo" list, rather than > having > > it > > > > go > > > > > > > chronologically by when each JIRA ticket was resolved would > make > > it > > > > > even > > > > > > > more developer-friendly. For example, here's the stuff you > have > > to > > > > do > > > > > to > > > > > > > your structure classes. On the client side, here are the > changes > > > to > > > > > the > > > > > > > server interface, the Gremlin DSL changes organized by step, > etc. > > > > > > > > > > > > > > On Wed, Oct 7, 2015 at 4:16 AM, Stephen Mallette < > > > > spmalle...@gmail.com > > > > > > > > > > > > > wrote: > > > > > > > > > > > > > >> I'm going to resurrect this old-ish thread as we didn't really > > > draw > > > > to > > > > > > any > > > > > > >> particular conclusion and new releases are looming. Just to > > save > > > > > folks > > > > > > >> from having to re-read the thread itself, the basic summary is > > > that > > > > we > > > > > > want > > > > > > >> to make it easy for implementers and users to consume our new > > > > > > releases. We > > > > > > >> largely rely on two things right now to convey that > information: > > > > > > >> > > > > > > >> 1. JIRA and the "breaking" label > > > > > > >> 2. CHANGELOG (which is generated from JIRA) > > > > > > >> > > > > > > >> The idea is that people reading CHANGELOG check in on JIRA to > > see > > > > how > > > > > to > > > > > > >> resolve their upgrade issues. I find two issues with that. > > > First, I > > > > > > >> wouldn't like to do that if I were a user (i.e. resolving JIRA > > > URLs > > > > to > > > > > > find > > > > > > >> out what's going on in a release). Second, we have no > > "document" > > > > that > > > > > > >> yields a nice summary of all change. We used to have a bit > more > > > > > > verbosity > > > > > > >> in the CHANGELOG when it wasn't just JIRA, but even then it > > wasn't > > > > > > pretty > > > > > > >> and didn't provide much information on how to upgrade. > > > > > > >> > > > > > > >> I'd proposed the idea in this thread that we create a > > "companion" > > > > > > document > > > > > > >> in /docs to CHANGELOG. This document would be the thing we > > point > > > > > folks > > > > > > to > > > > > > >> when we have a release and it roughly contains: > > > > > > >> > > > > > > >> 1. A summary of important/major changes. > > > > > > >> 2. A section for implementers that describes how to resolve > > > > "breaking" > > > > > > >> change > > > > > > >> 3. A section for users that describes how to resolve > "breaking" > > > > > change. > > > > > > >> > > > > > > >> Anyone like this idea? If not, are there other ideas on how > we > > > can > > > > > > improve > > > > > > >> here? > > > > > > >> > > > > > > >> > > > > > > >> > > > > > > >> > > > > > > >> On Wed, Sep 9, 2015 at 9:49 AM, Stephen Mallette < > > > > > spmalle...@gmail.com> > > > > > > >> wrote: > > > > > > >> > > > > > > >>> I added a section about "Deprecation" to CONTRIBUTING that > > > > describes > > > > > > the > > > > > > >>> patterns we've been using informally: > > > > > > >>> > > > > > > >>> > > > > > > >>> > > > > > > >> > > > > > > > > > > > > > > > > > > > > > https://github.com/apache/incubator-tinkerpop/blob/dd6bcfb6b23525863e1073e304f6a5aea0ca3c35/CONTRIBUTING.asciidoc#deprecation > > > > > > >>> > > > > > > >>> I added in one additional thing we haven't been doing: > Creating > > > > JIRA > > > > > > >>> issues to track deprecated methods for future removal. It > seems > > > > like > > > > > > >> that's > > > > > > >>> an easy way to not lose track of anything we deprecated (i.e. > > as > > > > soon > > > > > > as > > > > > > >> we > > > > > > >>> deprecate something - create a ticket in jira for future > > > removal). > > > > > We > > > > > > >> can > > > > > > >>> then periodically roll through those JIRA issues and have a > > > > community > > > > > > >>> discussion about when it is prudent to remove something for > > good. > > > > > > Sound > > > > > > >>> good? > > > > > > >>> > > > > > > >>> I replied to this thread as it related to "breaking" change > and > > > how > > > > > we > > > > > > >>> convey it to folks. Haven't seen any more replies to this > > thread > > > > > > since - > > > > > > >>> any new ideas around breaking/changelog/etc? > > > > > > >>> > > > > > > >>> On Wed, Sep 2, 2015 at 4:53 PM, Stephen Mallette < > > > > > spmalle...@gmail.com > > > > > > > > > > > > > >>> wrote: > > > > > > >>> > > > > > > >>>> The "breaking" label seems a bit too broad - especially > after > > > > going > > > > > > >>>> through the details of the release process today. i do > > believe > > > we > > > > > > need > > > > > > >>>> some additional categorization in there - especially for > users > > > who > > > > > are > > > > > > >>>> trying to figure out what's going on when they bump version. > > i > > > > > don't > > > > > > >> think > > > > > > >>>> we should shove it all into CHANGELOG though - i have the > > sense > > > > > that > > > > > > >> for > > > > > > >>>> it to be useful we'll need more than just one-line bullets. > > For > > > > > > >> instance, > > > > > > >>>> take a look at what i just pushed into this issue as a > > comment: > > > > > > >>>> > > > > > > >>>> > > > > > > >>>> > > > > > > >> > > > > > > > > > > > > > > > > > > > > > https://issues.apache.org/jira/browse/TINKERPOP3-690?focusedCommentId=14727966&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14727966 > > > > > > >>>> > > > > > > >>>> I needed several sentences plus a link to make it easy for > > folks > > > > to > > > > > > know > > > > > > >>>> what to do. perhaps, we have a companion document in /docs > > for > > > > each > > > > > > >>>> version that describes what to expect with the release. in > > that > > > > way > > > > > > we > > > > > > >> can > > > > > > >>>> be more descriptive, better summarize JIRA tickets, create > the > > > > > > sections > > > > > > >> you > > > > > > >>>> described and have room to expand as needed, etc. If we did > > it > > > > this > > > > > > >> way I > > > > > > >>>> don't think it would be terrible to keep our single > "breaking" > > > > label > > > > > > in > > > > > > >>>> JIRA for our internal use, because on release day we'd roll > > > > through > > > > > > the > > > > > > >>>> breaking labels on that release and make sure they were > > > summarized > > > > > > >> properly > > > > > > >>>> in the companion doc. > > > > > > >>>> > > > > > > >>>> > > > > > > >>>> On Wed, Sep 2, 2015 at 3:35 PM, Marko Rodriguez < > > > > > okramma...@gmail.com > > > > > > > > > > > > > >>>> wrote: > > > > > > >>>> > > > > > > >>>>> Hi Stephen (cc: others), > > > > > > >>>>> > > > > > > >>>>> I think you had an email about this at some point, but I > > can't > > > > find > > > > > > it. > > > > > > >>>>> So I will just say what I think is cool and please correct > me > > > if > > > > > > there > > > > > > >> is > > > > > > >>>>> already a pattern in place. > > > > > > >>>>> > > > > > > >>>>> I think we should make a distinction between "breaking" > > change > > > > and > > > > > > >>>>> "deprecating" change. Next, in the CHANGELOG, when there > is a > > > > > > >>>>> breaking/deprecating change we should tag it like this: > > > > > > >>>>> > > > > > > >>>>> * Simplified `SackValueStep` so it now supports both > > > > > > >>>>> `sack(function)` and sack(function).by()`. (*deprecating*) > > > > > > >>>>> > > > > > > >>>>> Then, at the bottom of the CHANGELOG (for that release) we > > have > > > > two > > > > > > >>>>> sections: Breaking Solutions and Deprecating Solutions. For > > the > > > > > > example > > > > > > >>>>> above. > > > > > > >>>>> > > > > > > >>>>> Deprecating Solutions > > > > > > >>>>> ------------------------------ > > > > > > >>>>> > > > > > > >>>>> * `GremlinTraversal.sack(function,string)` can be > > > > rewritten > > > > > > >>>>> using `GraphTraversal.sack(function).by(string)`. > > > > > > >>>>> > > > > > > >>>>> This way, we not only explicitly show people what is > > deprecated > > > > and > > > > > > >> what > > > > > > >>>>> is "broken," but also how to solve it. > > > > > > >>>>> > > > > > > >>>>> Perhaps this is taking it too far, but we could even have > > like: > > > > > > >>>>> > > > > > > >>>>> * deprecating/breaking graph system vendor > > > > > > >>>>> * deprecating/breaking graph language vendor > > > > > > >>>>> * deprecating/breaking user code > > > > > > >>>>> > > > > > > >>>>> Thoughts?, > > > > > > >>>>> Marko. > > > > > > >>>>> > > > > > > >>>>> http://markorodriguez.com > > > > > > >>>>> > > > > > > >>>>> > > > > > > >>>> > > > > > > >>> > > > > > > >> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > Have a good one, > > > > Jason > > > > > > > > > >
