I took a swipe at this, but after some thought given my previous attempt, i came up with something more straightforward that didn't have to touch a bunch of Daniel's pre-processor stuff. In fact, I think it works so easily that putting it into 3.0.2 wouldn't be a big deal at all. One entry to the pom gives us what we need:
https://github.com/apache/incubator-tinkerpop/commit/12e339998b0024741a2cc18795f65ff43d70d467 Basically I just generate an "upgrade book" from upgrade.asciidoc which is generated in the same fashion as our "reference book" from index.asciidoc. This pattern is nice because it means that anytime we have a new class of documentation it just means adding a new "book". So we could have a "tutorial book", a "developers book", etc. This also answers the question of continuity of a single "upgrade" document that you can just scroll through end-to-end like our docs because it will have a table of contents and all that. Check out my screenshot attached. Anyway, the best part for me is that this was a super easy change, doesn't threaten the stability of our doc generation process with new stuff and everything still deploys via publish-docs.sh. Any thoughts on this slightly revised approach? On Mon, Oct 12, 2015 at 3:31 PM, Stephen Mallette <spmalle...@gmail.com> wrote: > Based on the feedback I've seen here, I'm going to move forward with > re-organizing the docs in the fashion I presented. I think that this is > going to represent a pretty large change to our documentation process and > as such, the work will be done in master to be part of 3.1.0. It might be > a little weird, but I think we should do the 3.0.2 release documentation in > master once this work is done - so stuff will be a little our of synch for > this next release, but going forward we'll have a good solid pattern to > follow. > > https://issues.apache.org/jira/browse/TINKERPOP3-883 > > On Fri, Oct 9, 2015 at 8:20 AM, Dylan Millikin <dylan.milli...@gmail.com> > wrote: > >> 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 >> > > > > >> > > > >> > > >> > >> > >
