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 >
