)]}'
{"guidelines/microversions-architecture.rst":[{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":13,"context_line":""},{"line_number":14,"context_line":"Stability and compatibility in APIs grows trust by the users. They"},{"line_number":15,"context_line":"feel you are looking out for them, and it is worth their time to"},{"line_number":16,"context_line":"invest in your platform."},{"line_number":17,"context_line":""},{"line_number":18,"context_line":"A User-First Perspective"},{"line_number":19,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_44c2d534","line":16,"updated":"2017-03-15 16:19:35.000000000","message":"These two paragraphs sound like good background for a problem statement, but are not themselves the actual problem statement. I suspect you already realize this, but I thought I better mention it anyway.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":30,"context_line":""},{"line_number":31,"context_line":"Jackson has decided to leave tech and take up goat farming. His"},{"line_number":32,"context_line":"application should continue to work without changes even after the"},{"line_number":33,"context_line":"OpenStack cloud it\u0027s running against has been upgraded multiple times."},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"Emma the Active"},{"line_number":36,"context_line":"---------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_641271b6","line":33,"updated":"2017-03-15 16:19:35.000000000","message":"There are effectively two personas here:\n\n* jackson himself, who made a good contribution and left\n* other people who use jackson\u0027s stuff and want to carry on doing so because it solves a problem and having to change it is a pita because jackson is the absent\n\nThe persona that matters most is the latter?","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":35,"context_line":"Emma the Active"},{"line_number":36,"context_line":"---------------"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"Emma is the kind of person that loves new features and eagerly awaits"},{"line_number":39,"context_line":"her OpenStack cloud upgrades to see the new things she can do. She"},{"line_number":40,"context_line":"should be able to have her application work fine across upgrades, and"},{"line_number":41,"context_line":"then be able to modify it to take advantages of new features exposed"}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_1862aad9","line":38,"range":{"start_line":38,"start_character":27,"end_line":38,"end_character":31},"updated":"2017-07-20 19:26:16.000000000","message":"who","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":53,"context_line":"all simultaneously."},{"line_number":54,"context_line":""},{"line_number":55,"context_line":"(Note: this is what our own nodepool does that runs all the OpenStack"},{"line_number":56,"context_line":"upstream tests)"},{"line_number":57,"context_line":""},{"line_number":58,"context_line":"Aiden the Cloud Operator"},{"line_number":59,"context_line":"------------------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_78a87eda","line":56,"updated":"2017-07-20 19:26:16.000000000","message":"period","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":55,"context_line":"(Note: this is what our own nodepool does that runs all the OpenStack"},{"line_number":56,"context_line":"upstream tests)"},{"line_number":57,"context_line":""},{"line_number":58,"context_line":"Aiden the Cloud Operator"},{"line_number":59,"context_line":"------------------------"},{"line_number":60,"context_line":""},{"line_number":61,"context_line":"Aiden knows he has a lot of users of the OpenStack API at his"}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_d874329f","line":58,"range":{"start_line":58,"start_character":0,"end_line":58,"end_character":5},"updated":"2017-07-20 19:26:16.000000000","message":"Aiden?  Really?  http://www.babynamewizard.com/voyager#prefix\u003daiden\u0026sw\u003dboth\u0026exact\u003dfalse","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":68,"context_line":""},{"line_number":69,"context_line":"Olivia wants to get her feature added to Nova which needs exposing"},{"line_number":70,"context_line":"through the API. She\u0027d like to be able to get that landed during a"},{"line_number":71,"context_line":"release, and not have to wait 3 years for an eventual API rewrite."},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"Requirements"},{"line_number":74,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_0487fdb5","line":71,"updated":"2017-03-15 16:19:35.000000000","message":"This is the one that identifies one of the main sore points in the stability guidelines. Some people say \"how about we just not change stuff?\". One of the answers to that is \"because Olivia, who we don\u0027t want to dismiss or disregard\".","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":83,"context_line":"  optional feature is a feature that can\u0027t be depended on by an"},{"line_number":84,"context_line":"  application writer. Or worse: if it\u0027s used, it\u0027s a lock-in to that"},{"line_number":85,"context_line":"  cloud. That means software has to be rewritten for every cloud, or"},{"line_number":86,"context_line":"  written with a horrible kluge layer."},{"line_number":87,"context_line":"- It needs to be really clear exactly what a particular cloud\u0027s API"},{"line_number":88,"context_line":"  supports."},{"line_number":89,"context_line":"- Older applications must not be broken by new features, or need to be"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_976ebdc7","line":86,"updated":"2017-03-15 16:19:35.000000000","message":"\"optional feature\" is another crucial piece. Some people interpret the thinking around microversions and interoperability as saying \"don\u0027t have optionality\" others as \"well you then must have really good discoverability and a concept of capabilities\". The gap between those two things needs to be narrowed.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":98,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":99,"context_line":""},{"line_number":100,"context_line":"One of the first things people jump to is that adding new fields is"},{"line_number":101,"context_line":"backwards compatible."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":".. note::"},{"line_number":104,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_77878161","line":101,"updated":"2017-03-15 16:19:35.000000000","message":"Ed\u0027s blog posting on interop has some perspective on this. Neither it nor this are perfectly obvious, but between the two it ought to be possible to find a common and understandable piece.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":102,"context_line":""},{"line_number":103,"context_line":".. note::"},{"line_number":104,"context_line":""},{"line_number":105,"context_line":"   The diagrams below are placeholders. None of the existing"},{"line_number":106,"context_line":"   diagramming tools such as ``blockdiag``, ``graphviz``, or"},{"line_number":107,"context_line":"   ``plantuml`` are expressive enough for what\u0027s needed here."},{"line_number":108,"context_line":""},{"line_number":109,"context_line":".. blockdiag::"},{"line_number":110,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_73ae6199","line":107,"range":{"start_line":105,"start_character":3,"end_line":107,"end_character":61},"updated":"2017-07-20 19:26:16.000000000","message":"actdiag ought to be adequate.  See e.g. stephenfin\u0027s work here: https://review.openstack.org/#/c/475810/","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":204,"context_line":""},{"line_number":205,"context_line":"- monotonically increasing"},{"line_number":206,"context_line":"- expressed via HTTP header"},{"line_number":207,"context_line":"- are sent on every request"},{"line_number":208,"context_line":"- global for a service (not per resource)"},{"line_number":209,"context_line":""},{"line_number":210,"context_line":"API Microversions are not:"}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_583dc22a","line":207,"range":{"start_line":207,"start_character":2,"end_line":207,"end_character":5},"updated":"2017-07-20 19:26:16.000000000","message":"strike","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":210,"context_line":"API Microversions are not:"},{"line_number":211,"context_line":""},{"line_number":212,"context_line":"- semver (this is common confusion)"},{"line_number":213,"context_line":"- guaranteed to be compatible between them"},{"line_number":214,"context_line":""},{"line_number":215,"context_line":""},{"line_number":216,"context_line":"API microversions are spiritually based upon Content Negotiation in"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_37efc9e9","line":213,"updated":"2017-03-15 16:19:35.000000000","message":"\"them\" is insufficiently anchored here to really know what you mean by \"compatible between\" means","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":219,"context_line":"good. If the server does not, a bad request is returned. If the user"},{"line_number":220,"context_line":"never specifies what they want, the minimum version of the API is"},{"line_number":221,"context_line":"assumed (this is the soft opt in for clients that existed before"},{"line_number":222,"context_line":"microversions)."},{"line_number":223,"context_line":""},{"line_number":224,"context_line":"Before Microversions, APIs in OpenStack had 3 mechanisms for"},{"line_number":225,"context_line":"evolution. Changing the API in every release, ignoring the multi cloud"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_b7b019f6","line":222,"updated":"2017-03-15 16:19:35.000000000","message":"In conversations about microversions I\u0027ve been in the point/value of defaulting to minimum is something that has been useful to make very clear at the start.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":221,"context_line":"assumed (this is the soft opt in for clients that existed before"},{"line_number":222,"context_line":"microversions)."},{"line_number":223,"context_line":""},{"line_number":224,"context_line":"Before Microversions, APIs in OpenStack had 3 mechanisms for"},{"line_number":225,"context_line":"evolution. Changing the API in every release, ignoring the multi cloud"},{"line_number":226,"context_line":"use case above (this is what Keystone / Glance do), provide a major"},{"line_number":227,"context_line":"version endpoint (this is what nearly every service has done at some"}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_b87cd6eb","line":224,"range":{"start_line":224,"start_character":7,"end_line":224,"end_character":20},"updated":"2017-07-20 19:26:16.000000000","message":"consistency of capitalization","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":226,"context_line":"use case above (this is what Keystone / Glance do), provide a major"},{"line_number":227,"context_line":"version endpoint (this is what nearly every service has done at some"},{"line_number":228,"context_line":"point), add extensions, and require end users to infer features from"},{"line_number":229,"context_line":"those (done by Nova, Cinder, Neutron and others)."},{"line_number":230,"context_line":""},{"line_number":231,"context_line":"This provides a 4th approach to evolution of an API."},{"line_number":232,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_17ae4d85","line":229,"updated":"2017-03-15 16:19:35.000000000","message":"This paragraph could be expanded to be more descriptive. As it currently stands it requires a fair bit of insight into history. Since presumably we are going to be sending people to this document for them to get that history...","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":226,"context_line":"use case above (this is what Keystone / Glance do), provide a major"},{"line_number":227,"context_line":"version endpoint (this is what nearly every service has done at some"},{"line_number":228,"context_line":"point), add extensions, and require end users to infer features from"},{"line_number":229,"context_line":"those (done by Nova, Cinder, Neutron and others)."},{"line_number":230,"context_line":""},{"line_number":231,"context_line":"This provides a 4th approach to evolution of an API."},{"line_number":232,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_985a3a81","line":229,"in_reply_to":"3a1ff146_17ae4d85","updated":"2017-07-20 19:26:16.000000000","message":"Could also stand to be bulleted out, or at least repunctuated.  It is tough to discern what are the three mechanisms.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":228,"context_line":"point), add extensions, and require end users to infer features from"},{"line_number":229,"context_line":"those (done by Nova, Cinder, Neutron and others)."},{"line_number":230,"context_line":""},{"line_number":231,"context_line":"This provides a 4th approach to evolution of an API."},{"line_number":232,"context_line":""},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"Microversions in Action"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_57b605dd","line":231,"updated":"2017-03-15 16:19:35.000000000","message":"Microversions provide a...","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":243,"context_line":""},{"line_number":244,"context_line":"Let\u0027s look at how this solves things for our stakeholders:"},{"line_number":245,"context_line":""},{"line_number":246,"context_line":"- Jackson: his application keeps running, v2.1 is v2.0. His application"},{"line_number":247,"context_line":"  needed to make 0 changes to run as it did before."},{"line_number":248,"context_line":""},{"line_number":249,"context_line":"- Emma: she can poll the Versions endpoint and discover that her cloud"}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_98cfda28","line":246,"range":{"start_line":246,"start_character":2,"end_line":246,"end_character":9},"updated":"2017-07-20 19:26:16.000000000","message":"Consider making these links back to their persona descriptions.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5bcb66ea46b744808cb9346ad2bde23fb1b1f3a","unresolved":false,"context_lines":[{"line_number":244,"context_line":"Let\u0027s look at how this solves things for our stakeholders:"},{"line_number":245,"context_line":""},{"line_number":246,"context_line":"- Jackson: his application keeps running, v2.1 is v2.0. His application"},{"line_number":247,"context_line":"  needed to make 0 changes to run as it did before."},{"line_number":248,"context_line":""},{"line_number":249,"context_line":"- Emma: she can poll the Versions endpoint and discover that her cloud"},{"line_number":250,"context_line":"  now supports 2.4. So she can start coding to those features in her"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a1ff146_1721edfb","line":247,"updated":"2017-03-15 16:19:35.000000000","message":"this looks/reads like it is describing nova, but we haven\u0027t talked about that in this document.\n\nInstead Jackson\u0027s code talked either no version and thus minimum version or is pinned to a particular version and that version is still around after upgrades, so his stuff still works.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"8ffc7f2741d34d36753a97c5106b585efab92190","unresolved":false,"context_lines":[{"line_number":333,"context_line":""},{"line_number":334,"context_line":"The Backwards Compatibility Fallacy"},{"line_number":335,"context_line":""},{"line_number":336,"context_line":"Nearly every conversation with a developer around this issue starts with \"why can\u0027t we just add more data to structures in backwards compatible ways\". This is how service providers like Amazon, Meetup, and others work."},{"line_number":337,"context_line":""},{"line_number":338,"context_line":"The problem is we aren\u0027t a proprietary company with 1 revision of our API stack in the wild at a time. We are an Open Source project with thousands of deployments all over the world, all on different code revisions and upgrade cadence."},{"line_number":339,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"dfeb2761_daa169fa","line":336,"updated":"2017-04-04 13:08:46.000000000","message":"Wrapping seems to have gone off the rails here and after line 375 below.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":335,"context_line":""},{"line_number":336,"context_line":"Nearly every conversation with a developer around this issue starts with \"why can\u0027t we just add more data to structures in backwards compatible ways\". This is how service providers like Amazon, Meetup, and others work."},{"line_number":337,"context_line":""},{"line_number":338,"context_line":"The problem is we aren\u0027t a proprietary company with 1 revision of our API stack in the wild at a time. We are an Open Source project with thousands of deployments all over the world, all on different code revisions and upgrade cadence."},{"line_number":339,"context_line":""},{"line_number":340,"context_line":"Let\u0027s play the exercise where we thought additive was good enough."},{"line_number":341,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_38ad6631","line":338,"range":{"start_line":338,"start_character":227,"end_line":338,"end_character":234},"updated":"2017-07-20 19:26:16.000000000","message":"cadences","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":384,"context_line":""},{"line_number":385,"context_line":"Nova v2.1/v2.0 Forever (nearly)"},{"line_number":386,"context_line":""},{"line_number":387,"context_line":"There are some details about how we implement microversions internally in Nova, which means our assumption is that we\u0027re supporting the base v2.1 API forever. We have the facility to raise the minimum version; however we\u0027ve stated the first time we\u0027re even going to have that conversation is in Barcelona in Fall of 2016. That doesn\u0027t mean we\u0027ll raise the minimum in Orzo, but we\u0027ll have our first conversation, with lots of data from operators and application developers to see how things are going, and what\u0027s a realistic path moving forward."},{"line_number":388,"context_line":""},{"line_number":389,"context_line":"One API - no more extensions"},{"line_number":390,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_d3fd3509","line":387,"range":{"start_line":387,"start_character":295,"end_line":387,"end_character":320},"updated":"2017-07-20 19:26:16.000000000","message":"?","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":384,"context_line":""},{"line_number":385,"context_line":"Nova v2.1/v2.0 Forever (nearly)"},{"line_number":386,"context_line":""},{"line_number":387,"context_line":"There are some details about how we implement microversions internally in Nova, which means our assumption is that we\u0027re supporting the base v2.1 API forever. We have the facility to raise the minimum version; however we\u0027ve stated the first time we\u0027re even going to have that conversation is in Barcelona in Fall of 2016. That doesn\u0027t mean we\u0027ll raise the minimum in Orzo, but we\u0027ll have our first conversation, with lots of data from operators and application developers to see how things are going, and what\u0027s a realistic path moving forward."},{"line_number":388,"context_line":""},{"line_number":389,"context_line":"One API - no more extensions"},{"line_number":390,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_533a45cd","line":387,"range":{"start_line":387,"start_character":367,"end_line":387,"end_character":371},"updated":"2017-07-20 19:26:16.000000000","message":"Presumably Ocata?\n\nAnywho, this probably needs to be reworked to talk about 2016 and the O release in the past tense.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":390,"context_line":""},{"line_number":391,"context_line":"There were multiple ways we could have gone about microversioning; one of the original suggestions was versions per resource. But the moment you start thinking about what the client code would look like to talk to that, you want to throw up a little bit. It was clear that to provide the best user experience we needed to draw a line in the sand and stop thinking about the Nova API as a toolkit to extend, and declare it as a solid thing that all users can expect from their clouds."},{"line_number":392,"context_line":""},{"line_number":393,"context_line":"The extensions mechanism is deprecated. All the extensions in the Nova tree are now in the Nova API. Over the next couple of cycles we\u0027ll be consolidating some of the code to make this more consistent, and eventually remove the possibility of out-of-tree extensions working at all. This allows the API to have a meaningful monotonically increasing API version that will mean the same thing across all deploys."},{"line_number":394,"context_line":""},{"line_number":395,"context_line":"This is also a signal to people working on Nova that \"innovating on the API out-of-tree\" is a thing we not only don\u0027t find valuable, but is fundamentally hostile to the creation of an application ecosystem for OpenStack."},{"line_number":396,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_737301b3","line":393,"range":{"start_line":393,"start_character":101,"end_line":393,"end_character":131},"updated":"2017-07-20 19:26:16.000000000","message":"We should think about statements like this in terms of how long this document is going to live, and how it\u0027s going to read at various points in the future.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":408,"context_line":""},{"line_number":409,"context_line":"Discoverability is not yet fully solved, as the policy that applies to a user is still hidden. We hope that with some of the upcoming work on Dynamic Policy in Keystone we can get that built into the API as well. That will give us a complete story where an application can know what it can do against a given cloud before it gets started (as a combination of supported microversion, and exposed policy)."},{"line_number":410,"context_line":""},{"line_number":411,"context_line":"And there is a lot of internal cleaing up, documentation, and testing still to do. The bulk of the Liberty cycle API work is going to be there to put some polish on what we\u0027ve got."},{"line_number":412,"context_line":""},{"line_number":413,"context_line":"A big thanks to Chris Yeoh"},{"line_number":414,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_f3e1512c","line":411,"range":{"start_line":411,"start_character":99,"end_line":411,"end_character":136},"updated":"2017-07-20 19:26:16.000000000","message":"see above","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":412,"context_line":""},{"line_number":413,"context_line":"A big thanks to Chris Yeoh"},{"line_number":414,"context_line":""},{"line_number":415,"context_line":"The journey that got us here was a long and hard one. It started 5 cycles ago at the Grizzly summit. A year ago no one on the team was convinced we had a path forward. Really hard things are some times really hard."},{"line_number":416,"context_line":""},{"line_number":417,"context_line":"Chris Yeoh was the point person for the API work through this whole time, and without his amazing patience and perseverance as we realized some terrible corners we\u0027d painted ourselves into, and work that had to be dropped on the floor, we probably wouldn\u0027t have come out the other side with anything nearly as productive as what we now have. We lost him this spring at far too young an age. This work is part of his legacy, and will be foundational for much of OpenStack for a long time to come."},{"line_number":418,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_13be0dff","line":415,"range":{"start_line":415,"start_character":65,"end_line":415,"end_character":99},"updated":"2017-07-20 19:26:16.000000000","message":"ditto","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":412,"context_line":""},{"line_number":413,"context_line":"A big thanks to Chris Yeoh"},{"line_number":414,"context_line":""},{"line_number":415,"context_line":"The journey that got us here was a long and hard one. It started 5 cycles ago at the Grizzly summit. A year ago no one on the team was convinced we had a path forward. Really hard things are some times really hard."},{"line_number":416,"context_line":""},{"line_number":417,"context_line":"Chris Yeoh was the point person for the API work through this whole time, and without his amazing patience and perseverance as we realized some terrible corners we\u0027d painted ourselves into, and work that had to be dropped on the floor, we probably wouldn\u0027t have come out the other side with anything nearly as productive as what we now have. We lost him this spring at far too young an age. This work is part of his legacy, and will be foundational for much of OpenStack for a long time to come."},{"line_number":418,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_3346a923","line":415,"range":{"start_line":415,"start_character":191,"end_line":415,"end_character":201},"updated":"2017-07-20 19:26:16.000000000","message":"sometimes","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"da7cbb3ad9e9b47aa6949e67d139e1bc546cf32a","unresolved":false,"context_lines":[{"line_number":424,"context_line":""},{"line_number":425,"context_line":"The Nova Microversion Spec - where this all began"},{"line_number":426,"context_line":"The Ironic Microversion Spec - a few minor differences, but has a great flow of expected client / server behavior"},{"line_number":427,"context_line":"The OpenStack API Working Group - where we are currently working on some best practice guidelines on how additional projects should implement microversions if that\u0027s a path they are considering."}],"source_content_type":"text/x-rst","patch_set":2,"id":"1f1a1f67_d32c154c","line":427,"updated":"2017-07-20 19:26:16.000000000","message":"Yah, there\u0027s now some real documentation on how microversions are handled, which should be linked from here.  Monty would probably be the person to identify the best top-level links there.","commit_id":"0577da064f8319a370ec577af1bde1d81e47c08a"},{"author":{"_account_id":5046,"name":"Lance Bragstad","email":"lbragstad@redhat.com","username":"ldbragst"},"change_message_id":"d07fdbb19e1de0697eef1e785c43ac31dd1968c9","unresolved":false,"context_lines":[{"line_number":204,"context_line":"Semver"},{"line_number":205,"context_line":"------"},{"line_number":206,"context_line":""},{"line_number":207,"context_line":"Semver makes a lot of assumptions"},{"line_number":208,"context_line":""},{"line_number":209,"context_line":""},{"line_number":210,"context_line":".. warning::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"bf3e73b7_5bda6b17","line":207,"updated":"2017-08-07 15:26:40.000000000","message":"This is exactly what happened in Atlanta when keystone had a conversation about microversions. At the time we seemed convinced semver was the answer. Are there any resources, blog posts, or examples that we can link to that explain where semver breaks down for our use cases?","commit_id":"c7ba22898b85a3c5960e42854e16bacb8d30ba7f"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f3d2568be7f91b207914ab61e0e4f91fbe28b53d","unresolved":false,"context_lines":[{"line_number":21,"context_line":"Let\u0027s take a step back and think about some stakeholders involved in"},{"line_number":22,"context_line":"OpenStack, and what they need and want out of it."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"Jackson the Absent"},{"line_number":25,"context_line":"------------------"},{"line_number":26,"context_line":""},{"line_number":27,"context_line":"Last year Jackson wrote an application that works against OpenStack;"}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_cf1ae415","line":24,"updated":"2017-09-05 15:49:36.000000000","message":"You should name this one \"Justin\" after Justin Santa Barbara who was an early OpenStack core person who stopped doing things because OpenStack not because he was unhappy, but because he was very happy that it had gotten good enough for his needs and he didn\u0027t need it to change in any way. In effect, \u0027he wrote an app that worked and then walked away\" :)","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"9e749c155cf4fe0f0be62629007c73ff5d34c511","unresolved":false,"context_lines":[{"line_number":21,"context_line":"Let\u0027s take a step back and think about some stakeholders involved in"},{"line_number":22,"context_line":"OpenStack, and what they need and want out of it."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"Jackson the Absent"},{"line_number":25,"context_line":"------------------"},{"line_number":26,"context_line":""},{"line_number":27,"context_line":"Last year Jackson wrote an application that works against OpenStack;"}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_30bf84d1","line":24,"in_reply_to":"7f287b81_cf1ae415","updated":"2017-09-05 19:39:26.000000000","message":"heh. Well name choice was based on most popular baby names of 2014 - https://www.babycenter.com/top-baby-names-2014.htm","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"1f3111fd55ab95709295882a4ed5a0d733f61729","unresolved":false,"context_lines":[{"line_number":30,"context_line":""},{"line_number":31,"context_line":"Jackson has decided to leave tech and take up goat farming. His"},{"line_number":32,"context_line":"application should continue to work without changes even after the"},{"line_number":33,"context_line":"OpenStack cloud it\u0027s running against has been upgraded multiple times."},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"Emma the Active"},{"line_number":36,"context_line":"---------------"}],"source_content_type":"text/x-rst","patch_set":4,"id":"bf659307_03f1a26b","line":33,"updated":"2018-03-28 14:32:51.000000000","message":"only problem with this use case, for me, is that even with microversions we still have a deprecation path.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f3d2568be7f91b207914ab61e0e4f91fbe28b53d","unresolved":false,"context_lines":[{"line_number":32,"context_line":"application should continue to work without changes even after the"},{"line_number":33,"context_line":"OpenStack cloud it\u0027s running against has been upgraded multiple times."},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"Emma the Active"},{"line_number":36,"context_line":"---------------"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"Emma is the kind of person that loves new features and eagerly awaits"}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_8fa05ca7","line":35,"updated":"2017-09-05 15:49:36.000000000","message":"I want to make a joke here and suggest someone we all know who always wants the absolute latest API thing - but I honestly can\u0027t think of anyone. Maybe dims because of all his go/etcd excitement? \"Davanum the Active\" has a nice ring to it ...","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f3d2568be7f91b207914ab61e0e4f91fbe28b53d","unresolved":false,"context_lines":[{"line_number":41,"context_line":"then be able to modify it to take advantages of new features exposed"},{"line_number":42,"context_line":"in the API."},{"line_number":43,"context_line":""},{"line_number":44,"context_line":"Sophia the Multi-Cloud Integrator"},{"line_number":45,"context_line":"---------------------------------"},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"Sophia has an application that spans multiple OpenStack clouds run by"}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_cf6c249e","line":44,"updated":"2017-09-05 15:49:36.000000000","message":"Nobody has ever called me Sophia before.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f3d2568be7f91b207914ab61e0e4f91fbe28b53d","unresolved":false,"context_lines":[{"line_number":55,"context_line":"(Note: this is what our own nodepool does that runs all the OpenStack"},{"line_number":56,"context_line":"upstream tests)"},{"line_number":57,"context_line":""},{"line_number":58,"context_line":"Aiden the Cloud Operator"},{"line_number":59,"context_line":"------------------------"},{"line_number":60,"context_line":""},{"line_number":61,"context_line":"Aiden knows he has a lot of users of the OpenStack API at his"}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_4f839405","line":58,"updated":"2017-09-05 15:49:36.000000000","message":"Mohammed or Tim","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f3d2568be7f91b207914ab61e0e4f91fbe28b53d","unresolved":false,"context_lines":[{"line_number":63,"context_line":"world are, so that he can keep an eye on the far future of whether"},{"line_number":64,"context_line":"it\u0027s ever safe to disable really old features in his cloud."},{"line_number":65,"context_line":""},{"line_number":66,"context_line":"Olivia the Contributor"},{"line_number":67,"context_line":"----------------------"},{"line_number":68,"context_line":""},{"line_number":69,"context_line":"Olivia wants to get her feature added to Nova which needs exposing"}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_2f860815","line":66,"updated":"2017-09-05 15:49:36.000000000","message":"I like Olivia","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"1f3111fd55ab95709295882a4ed5a0d733f61729","unresolved":false,"context_lines":[{"line_number":102,"context_line":"   TODO(sdague): people immediately jump to being able to just add new"},{"line_number":103,"context_line":"   fields. That works really well with one installation under single"},{"line_number":104,"context_line":"   entity control, but not with multiple. Diagrams would be best here"},{"line_number":105,"context_line":"   to help visualize it."},{"line_number":106,"context_line":""},{"line_number":107,"context_line":""},{"line_number":108,"context_line":"Microversion Overview"}],"source_content_type":"text/x-rst","patch_set":4,"id":"bf659307_b5b6e9f9","line":105,"updated":"2018-03-28 14:32:51.000000000","message":"would love to know a little more about the proposed diagrams here","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3653a6c86113fa2797b622071ff80ef2911c7583","unresolved":false,"context_lines":[{"line_number":119,"context_line":""},{"line_number":120,"context_line":"- semver (this is common confusion)"},{"line_number":121,"context_line":"- guaranteed to be compatible between them"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":""},{"line_number":124,"context_line":"API microversions are spiritually based upon Content Negotiation in"},{"line_number":125,"context_line":"HTTP. During a request the user requests the version of the API they"}],"source_content_type":"text/x-rst","patch_set":4,"id":"3f4b6375_fdafbd91","line":122,"updated":"2017-10-19 16:03:44.000000000","message":"addition:\n\n - restful in a strict sense\n\nbecause with microversions a URL is not representing a resource. I can represent anything (or nothing), depending on which microversion is sent. I think it\u0027s important to mention, because nearly everybody overlooks it.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"1f3111fd55ab95709295882a4ed5a0d733f61729","unresolved":false,"context_lines":[{"line_number":119,"context_line":""},{"line_number":120,"context_line":"- semver (this is common confusion)"},{"line_number":121,"context_line":"- guaranteed to be compatible between them"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":""},{"line_number":124,"context_line":"API microversions are spiritually based upon Content Negotiation in"},{"line_number":125,"context_line":"HTTP. During a request the user requests the version of the API they"}],"source_content_type":"text/x-rst","patch_set":4,"id":"bf659307_631dfebb","line":122,"in_reply_to":"3f4b6375_fdafbd91","updated":"2018-03-28 14:32:51.000000000","message":"i\u0027m not sure this makes sense here, i agree that microversions themselves are not really \"restful\", but i think the issue you are pointing is kind of orthogonal to the URL requests.\n\nyou can have microversion headers with or without a strictly restful URL. since it would all depend on the URL, i\u0027m not sure we need to mention this here.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3653a6c86113fa2797b622071ff80ef2911c7583","unresolved":false,"context_lines":[{"line_number":151,"context_line":"Let\u0027s look at how this solves things for our stakeholders:"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"- Jackson: his application keeps running, v2.1 is v2.0. His application"},{"line_number":154,"context_line":"  needed to make 0 changes to run as it did before."},{"line_number":155,"context_line":""},{"line_number":156,"context_line":"- Emma: she can poll the Versions endpoint and discover that her cloud"},{"line_number":157,"context_line":"  now supports 2.4. So she can start coding to those features in her"}],"source_content_type":"text/x-rst","patch_set":4,"id":"3f4b6375_dd940147","line":154,"updated":"2017-10-19 16:03:44.000000000","message":"This needs adding \"Never removed\" to your \"Microversions are\". Otherwise the situation for Jackson is worse than without microversions.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"1f3111fd55ab95709295882a4ed5a0d733f61729","unresolved":false,"context_lines":[{"line_number":151,"context_line":"Let\u0027s look at how this solves things for our stakeholders:"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"- Jackson: his application keeps running, v2.1 is v2.0. His application"},{"line_number":154,"context_line":"  needed to make 0 changes to run as it did before."},{"line_number":155,"context_line":""},{"line_number":156,"context_line":"- Emma: she can poll the Versions endpoint and discover that her cloud"},{"line_number":157,"context_line":"  now supports 2.4. So she can start coding to those features in her"}],"source_content_type":"text/x-rst","patch_set":4,"id":"bf659307_039682f1","line":154,"in_reply_to":"3f4b6375_dd940147","updated":"2018-03-28 14:32:51.000000000","message":"i think i get what you are saying here, i added a similar remark in the Jackson description above.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3653a6c86113fa2797b622071ff80ef2911c7583","unresolved":false,"context_lines":[{"line_number":184,"context_line":""},{"line_number":185,"context_line":"- Olivia: she can now help evolve the Nova API in a safe way, knowing"},{"line_number":186,"context_line":"  that she\u0027s not going to break existing users, but will still be able"},{"line_number":187,"context_line":"  to support new things needed by OpenStack."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":""},{"line_number":190,"context_line":"Implementations in the OpenStack Ecosystem"}],"source_content_type":"text/x-rst","patch_set":4,"id":"3f4b6375_bd914555","line":187,"updated":"2017-10-19 16:03:44.000000000","message":"This has a big red \"assuming she never makes mistakes\" hidden :)","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"1f3111fd55ab95709295882a4ed5a0d733f61729","unresolved":false,"context_lines":[{"line_number":184,"context_line":""},{"line_number":185,"context_line":"- Olivia: she can now help evolve the Nova API in a safe way, knowing"},{"line_number":186,"context_line":"  that she\u0027s not going to break existing users, but will still be able"},{"line_number":187,"context_line":"  to support new things needed by OpenStack."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":""},{"line_number":190,"context_line":"Implementations in the OpenStack Ecosystem"}],"source_content_type":"text/x-rst","patch_set":4,"id":"bf659307_75a3719f","line":187,"in_reply_to":"3f4b6375_bd914555","updated":"2018-03-28 14:32:51.000000000","message":"sure, but that\u0027s implied everywhere in software engineering XD","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f3d2568be7f91b207914ab61e0e4f91fbe28b53d","unresolved":false,"context_lines":[{"line_number":190,"context_line":"Implementations in the OpenStack Ecosystem"},{"line_number":191,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":192,"context_line":""},{"line_number":193,"context_line":"TODO(sdague): give a survey of where this is currently implemented"},{"line_number":194,"context_line":""},{"line_number":195,"context_line":""},{"line_number":196,"context_line":"Why isn\u0027t this just..."}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_4f5954fc","line":193,"updated":"2017-09-05 15:49:36.000000000","message":"Mentioned below, but I think we should include both client and server implementations here. Happy to help flesh it out.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f3d2568be7f91b207914ab61e0e4f91fbe28b53d","unresolved":false,"context_lines":[{"line_number":254,"context_line":"--------"},{"line_number":255,"context_line":""},{"line_number":256,"context_line":"SDKs"},{"line_number":257,"context_line":"----"},{"line_number":258,"context_line":""},{"line_number":259,"context_line":"Client Applications"},{"line_number":260,"context_line":"-------------------"}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_6f78908e","line":257,"updated":"2017-09-05 15:49:36.000000000","message":"We\u0027ve got a consuming service discovery document we should link to here. It\u0027s also probably worth mentioning the ksa consume implementation. I can add some of that as a followup if you like.\n\nI\u0027ve also got some docs written somewhere but I think not merged about strategy for dealing iwth microversions for shade that I can totally generalize, propose and either put in here or just link to a second doc.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f3d2568be7f91b207914ab61e0e4f91fbe28b53d","unresolved":false,"context_lines":[{"line_number":257,"context_line":"----"},{"line_number":258,"context_line":""},{"line_number":259,"context_line":"Client Applications"},{"line_number":260,"context_line":"-------------------"},{"line_number":261,"context_line":""},{"line_number":262,"context_line":"CLIs"},{"line_number":263,"context_line":"----"}],"source_content_type":"text/x-rst","patch_set":4,"id":"7f287b81_2fce08b4","line":260,"updated":"2017-09-05 15:49:36.000000000","message":"I definitely have thoughts on this one and will do a follow up with it.\n\nOf primary concern, I think, is writing somehing that covers the two different worldviews on consumption - that is, the way python-*client works (upgrade the microversion  holistically across the Client object) and the way ksa/shade works (don\u0027t put microversion in constructor, instead provide it per-call as needed/desired)\n\nI have an obvious preference between the two, but I think there\u0027s a good argument to be made for the thing that isn\u0027t my preference, so giving them both a good philosophical write up is likely valuable to everyone.","commit_id":"0440b262dfce8e726e3d92b3d985e3e989c23de3"}]}