)]}'
{"guidelines/microversion_specification.rst":[{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"a51ea40e23d0e60a70f51fff589389b8f3b075dd","unresolved":false,"context_lines":[{"line_number":25,"context_line":"  between backwards compatible and backwards incompatible changes in"},{"line_number":26,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":27,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":28,"context_line":"  is a backwards incompatible one."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"There are minimum and maximum versions which are used to describe what the"},{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da85f559_c5d85120","line":28,"updated":"2015-11-09 11:46:32.000000000","message":"The comment of \"Salvatore Orlando\" from https://review.openstack.org/#/c/187112/11/guidelines/microversion_specification.rst\n\n One thing that is not clear to API developers (well at least one API developer...) is\n when a backward compatible change deserve an increment in X and Y.\n\n Personally I believe increments in X should be used very sparingly.\n That is the case of a major overhaul of the API. For instance:\n  1) a number of endpoints get replaced by others\n  2) paradigms shifts from synchronous to asynchronous or vice versa\n  3) Drastic changes in API consumer workflow\n\n I reckon the guideline is the right place to provide this kind of clarification","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf2eb1647a8a398e57bd200ca9d4473a8639d9c5","unresolved":false,"context_lines":[{"line_number":25,"context_line":"  between backwards compatible and backwards incompatible changes in"},{"line_number":26,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":27,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":28,"context_line":"  is a backwards incompatible one."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"There are minimum and maximum versions which are used to describe what the"},{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a8ffd7b_d2de876c","line":28,"in_reply_to":"da85f559_405d2fe8","updated":"2015-11-26 08:41:40.000000000","message":"Done except 2)","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"7ad69c71be46de398aaef8f9232b06fd9622e376","unresolved":false,"context_lines":[{"line_number":25,"context_line":"  between backwards compatible and backwards incompatible changes in"},{"line_number":26,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":27,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":28,"context_line":"  is a backwards incompatible one."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"There are minimum and maximum versions which are used to describe what the"},{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da85f559_405d2fe8","line":28,"in_reply_to":"da85f559_c5d85120","updated":"2015-11-09 12:00:55.000000000","message":"Hi Salvatore\n\nAdditional examples are good as the guideline.\n1) and 3) seems good for me, but 2) doesn\u0027t seem enough to bump X because I am feeling small change. maybe you are imaging the change affects so much, can you provide some samples as the case?","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"a51ea40e23d0e60a70f51fff589389b8f3b075dd","unresolved":false,"context_lines":[{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"},{"line_number":32,"context_line":"most recent versions supported. The minimum version can be increased when"},{"line_number":33,"context_line":"supporting old clients is too great a burden. Increasing the minimum version"},{"line_number":34,"context_line":"means break the old clients, this happen very rarely also."},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da85f559_05f6598f","line":34,"updated":"2015-11-09 11:46:32.000000000","message":"The comment of \"Salvatore Orlando\" from https://review.openstack.org/#/c/187112/11/guidelines/microversion_specification.rst\n\n \"means break\" should probably be \"means breaking\"\n\n s/happen/happens/","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf2eb1647a8a398e57bd200ca9d4473a8639d9c5","unresolved":false,"context_lines":[{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"},{"line_number":32,"context_line":"most recent versions supported. The minimum version can be increased when"},{"line_number":33,"context_line":"supporting old clients is too great a burden. Increasing the minimum version"},{"line_number":34,"context_line":"means break the old clients, this happen very rarely also."},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a8ffd7b_12f40ff0","line":34,"in_reply_to":"da85f559_05f6598f","updated":"2015-11-26 08:41:40.000000000","message":"Done","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"a51ea40e23d0e60a70f51fff589389b8f3b075dd","unresolved":false,"context_lines":[{"line_number":35,"context_line":""},{"line_number":36,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"},{"line_number":38,"context_line":"without accepting all the changes before X in the same request. The API changes"},{"line_number":39,"context_line":"in X+1 version will hide in the X and early version. That also means specific"},{"line_number":40,"context_line":"version keeps all the same always since it\u0027s introduced."},{"line_number":41,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"da85f559_25835dce","line":38,"updated":"2015-11-09 11:46:32.000000000","message":"The comment of \"Salvatore Orlando\" from https://review.openstack.org/#/c/187112/11/guidelines/microversion_specification.rst\n\n It\u0027s not just hiding. Also all the behavioural changes introduced by\n version X+1 should not be available in X.\n\n Imagine, for instance, that version X+1 introduces a behaviour\n where by omitting network_id in a POST to \u003cneutron\u003e/v2.0/subnets\n triggers auto-generation of a network. In version X that same\n payload would result in a 400 instead, and the same behaviour\n should be preserved for version X even after X+1 is introduced.","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf2eb1647a8a398e57bd200ca9d4473a8639d9c5","unresolved":false,"context_lines":[{"line_number":35,"context_line":""},{"line_number":36,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"},{"line_number":38,"context_line":"without accepting all the changes before X in the same request. The API changes"},{"line_number":39,"context_line":"in X+1 version will hide in the X and early version. That also means specific"},{"line_number":40,"context_line":"version keeps all the same always since it\u0027s introduced."},{"line_number":41,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a8ffd7b_52c85722","line":38,"in_reply_to":"da85f559_25835dce","updated":"2015-11-26 08:41:40.000000000","message":"Yes, right.\nOn microversion, API service needs to keep the same behavior on the same microversion even after implementing a new microversion\u0027s behavior.\n\nThat is useful for interoperability: If API users specify the same microversion on different clouds, the behavior should be the same between clouds.","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"a51ea40e23d0e60a70f51fff589389b8f3b075dd","unresolved":false,"context_lines":[{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"},{"line_number":38,"context_line":"without accepting all the changes before X in the same request. The API changes"},{"line_number":39,"context_line":"in X+1 version will hide in the X and early version. That also means specific"},{"line_number":40,"context_line":"version keeps all the same always since it\u0027s introduced."},{"line_number":41,"context_line":""},{"line_number":42,"context_line":"Version Discovery"},{"line_number":43,"context_line":"-----------------"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da85f559_255a7d84","line":40,"updated":"2015-11-09 11:46:32.000000000","message":"The comment of \"Salvatore Orlando\" from https://review.openstack.org/#/c/187112/11/guidelines/microversion_specification.rst\n\n I am not able to understand the meaning of the last sentence","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf2eb1647a8a398e57bd200ca9d4473a8639d9c5","unresolved":false,"context_lines":[{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"},{"line_number":38,"context_line":"without accepting all the changes before X in the same request. The API changes"},{"line_number":39,"context_line":"in X+1 version will hide in the X and early version. That also means specific"},{"line_number":40,"context_line":"version keeps all the same always since it\u0027s introduced."},{"line_number":41,"context_line":""},{"line_number":42,"context_line":"Version Discovery"},{"line_number":43,"context_line":"-----------------"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a8ffd7b_321033a8","line":40,"in_reply_to":"da85f559_255a7d84","updated":"2015-11-26 08:41:40.000000000","message":"Done","commit_id":"e913c353ac1c5253b62e4b5d7a47636b2759aefd"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"31801ed9dac4827fee808622440c5cefed7a96ae","unresolved":false,"context_lines":[{"line_number":18,"context_line":""},{"line_number":19,"context_line":"* X will only be changed if a significant backwards incompatible"},{"line_number":20,"context_line":"  API change is made which affects the API as whole. That is, something"},{"line_number":21,"context_line":"  that is only very very rarely incremented."},{"line_number":22,"context_line":"* Y when you make any change to the API. Note that this includes"},{"line_number":23,"context_line":"  semantic changes which may not affect the input or output formats or"},{"line_number":24,"context_line":"  even originate in the API code layer. We are not distinguishing"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da85f559_ab302ee9","line":21,"updated":"2015-11-10 17:03:40.000000000","message":"i think we should drop \"very very\" here","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"afd9a82ff2428203e02148ae36831ce7f736cf57","unresolved":false,"context_lines":[{"line_number":18,"context_line":""},{"line_number":19,"context_line":"* X will only be changed if a significant backwards incompatible"},{"line_number":20,"context_line":"  API change is made which affects the API as whole. That is, something"},{"line_number":21,"context_line":"  that is only very very rarely incremented."},{"line_number":22,"context_line":"* Y when you make any change to the API. Note that this includes"},{"line_number":23,"context_line":"  semantic changes which may not affect the input or output formats or"},{"line_number":24,"context_line":"  even originate in the API code layer. We are not distinguishing"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a8ffd7b_caeed5b3","line":21,"in_reply_to":"da85f559_ab302ee9","updated":"2015-11-26 08:21:26.000000000","message":"Done","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"31801ed9dac4827fee808622440c5cefed7a96ae","unresolved":false,"context_lines":[{"line_number":26,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":27,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":28,"context_line":"  is a backwards incompatible one."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"There are minimum and maximum versions which are used to describe what the"},{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"},{"line_number":32,"context_line":"most recent versions supported. The minimum version can be increased when"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da85f559_6b780690","line":29,"updated":"2015-11-10 17:03:40.000000000","message":"i think we should add some examples as per Salvatore\u0027s comment in patch set 1","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"afd9a82ff2428203e02148ae36831ce7f736cf57","unresolved":false,"context_lines":[{"line_number":26,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":27,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":28,"context_line":"  is a backwards incompatible one."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"There are minimum and maximum versions which are used to describe what the"},{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"},{"line_number":32,"context_line":"most recent versions supported. The minimum version can be increased when"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a8ffd7b_17e881b3","line":29,"in_reply_to":"da85f559_6b780690","updated":"2015-11-26 08:21:26.000000000","message":"will fix it later","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"31801ed9dac4827fee808622440c5cefed7a96ae","unresolved":false,"context_lines":[{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"},{"line_number":32,"context_line":"most recent versions supported. The minimum version can be increased when"},{"line_number":33,"context_line":"supporting old clients is too great a burden. Increasing the minimum version"},{"line_number":34,"context_line":"means break the old clients, this happen very rarely also."},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da85f559_cbcfb27d","line":34,"updated":"2015-11-10 17:03:40.000000000","message":"s/means break/means breaking/\n\ns/happen/happens/","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"afd9a82ff2428203e02148ae36831ce7f736cf57","unresolved":false,"context_lines":[{"line_number":31,"context_line":"server can understand. The minimum and maximum versions are the oldest and"},{"line_number":32,"context_line":"most recent versions supported. The minimum version can be increased when"},{"line_number":33,"context_line":"supporting old clients is too great a burden. Increasing the minimum version"},{"line_number":34,"context_line":"means break the old clients, this happen very rarely also."},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a8ffd7b_0a3cdd2d","line":34,"in_reply_to":"da85f559_cbcfb27d","updated":"2015-11-26 08:21:26.000000000","message":"Done","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"31801ed9dac4827fee808622440c5cefed7a96ae","unresolved":false,"context_lines":[{"line_number":36,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"},{"line_number":38,"context_line":"without accepting all the changes before X in the same request. The API changes"},{"line_number":39,"context_line":"in X+1 version will hide in the X and early version. That also means specific"},{"line_number":40,"context_line":"version keeps all the same always since it\u0027s introduced."},{"line_number":41,"context_line":""},{"line_number":42,"context_line":"Client Interaction"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da85f559_0bfffa67","line":39,"updated":"2015-11-10 17:03:40.000000000","message":"Salvatore\u0027s comment from patchset 1 about hiding is still valid","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"afd9a82ff2428203e02148ae36831ce7f736cf57","unresolved":false,"context_lines":[{"line_number":36,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"},{"line_number":38,"context_line":"without accepting all the changes before X in the same request. The API changes"},{"line_number":39,"context_line":"in X+1 version will hide in the X and early version. That also means specific"},{"line_number":40,"context_line":"version keeps all the same always since it\u0027s introduced."},{"line_number":41,"context_line":""},{"line_number":42,"context_line":"Client Interaction"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a8ffd7b_f7cdbd5d","line":39,"in_reply_to":"da85f559_0bfffa67","updated":"2015-11-26 08:21:26.000000000","message":"will fix it later","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"31801ed9dac4827fee808622440c5cefed7a96ae","unresolved":false,"context_lines":[{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"},{"line_number":38,"context_line":"without accepting all the changes before X in the same request. The API changes"},{"line_number":39,"context_line":"in X+1 version will hide in the X and early version. That also means specific"},{"line_number":40,"context_line":"version keeps all the same always since it\u0027s introduced."},{"line_number":41,"context_line":""},{"line_number":42,"context_line":"Client Interaction"},{"line_number":43,"context_line":"------------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da85f559_eb22b600","line":40,"updated":"2015-11-10 17:03:40.000000000","message":"this last sentence should be cleaned up to be more explicit about the meaning. i think i understand it, but it is confusing to read.","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"afd9a82ff2428203e02148ae36831ce7f736cf57","unresolved":false,"context_lines":[{"line_number":37,"context_line":"It is not possible to request the feature introduced at Microversion X"},{"line_number":38,"context_line":"without accepting all the changes before X in the same request. The API changes"},{"line_number":39,"context_line":"in X+1 version will hide in the X and early version. That also means specific"},{"line_number":40,"context_line":"version keeps all the same always since it\u0027s introduced."},{"line_number":41,"context_line":""},{"line_number":42,"context_line":"Client Interaction"},{"line_number":43,"context_line":"------------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a8ffd7b_97ab111d","line":40,"in_reply_to":"da85f559_eb22b600","updated":"2015-11-26 08:21:26.000000000","message":"OK, I will try it.","commit_id":"10972b853a436db66800729bf261f3a7f71ac650"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"47a8817fa2f95c25ff0f7492dfaf5d605c4bea81","unresolved":false,"context_lines":[{"line_number":13,"context_line":"Versioning"},{"line_number":14,"context_line":"----------"},{"line_number":15,"context_line":""},{"line_number":16,"context_line":"Versioning of the API should be a single monotonic counter. It will be"},{"line_number":17,"context_line":"of the form X.Y where it follows the following convention:"},{"line_number":18,"context_line":""},{"line_number":19,"context_line":"* X will only be changed if a significant backwards incompatible"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da6ed579_3bc1b854","line":16,"range":{"start_line":16,"start_character":63,"end_line":16,"end_character":67},"updated":"2016-01-14 18:57:56.000000000","message":"should","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"47a8817fa2f95c25ff0f7492dfaf5d605c4bea81","unresolved":false,"context_lines":[{"line_number":16,"context_line":"Versioning of the API should be a single monotonic counter. It will be"},{"line_number":17,"context_line":"of the form X.Y where it follows the following convention:"},{"line_number":18,"context_line":""},{"line_number":19,"context_line":"* X will only be changed if a significant backwards incompatible"},{"line_number":20,"context_line":"  API change is made which affects the API as whole. That is, something"},{"line_number":21,"context_line":"  that is only very rarely incremented. X will be changed in the following"},{"line_number":22,"context_line":"  cases."}],"source_content_type":"text/x-rst","patch_set":4,"id":"da6ed579_dbfbbc79","line":19,"range":{"start_line":19,"start_character":4,"end_line":19,"end_character":8},"updated":"2016-01-14 18:57:56.000000000","message":"should","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"47a8817fa2f95c25ff0f7492dfaf5d605c4bea81","unresolved":false,"context_lines":[{"line_number":18,"context_line":""},{"line_number":19,"context_line":"* X will only be changed if a significant backwards incompatible"},{"line_number":20,"context_line":"  API change is made which affects the API as whole. That is, something"},{"line_number":21,"context_line":"  that is only very rarely incremented. X will be changed in the following"},{"line_number":22,"context_line":"  cases."},{"line_number":23,"context_line":"  ** A number of endpoints get replaced by others"},{"line_number":24,"context_line":"  ** Drastic changes in API consumer workflow"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da6ed579_5bf02c91","line":21,"range":{"start_line":21,"start_character":42,"end_line":21,"end_character":46},"updated":"2016-01-14 18:57:56.000000000","message":"should","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6824bc007e33de884b98a83672bcfdd80635626c","unresolved":false,"context_lines":[{"line_number":22,"context_line":"  cases."},{"line_number":23,"context_line":"  ** A number of endpoints get replaced by others"},{"line_number":24,"context_line":"  ** Drastic changes in API consumer workflow"},{"line_number":25,"context_line":"* Y when you make any change to the API. Note that this includes"},{"line_number":26,"context_line":"  semantic changes which may not affect the input or output formats or"},{"line_number":27,"context_line":"  even originate in the API code layer. We are not distinguishing"},{"line_number":28,"context_line":"  between backwards compatible and backwards incompatible changes in"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da6ed579_7b43cb42","line":25,"updated":"2016-01-14 11:35:51.000000000","message":"\"Y changes when...\"","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"47a8817fa2f95c25ff0f7492dfaf5d605c4bea81","unresolved":false,"context_lines":[{"line_number":22,"context_line":"  cases."},{"line_number":23,"context_line":"  ** A number of endpoints get replaced by others"},{"line_number":24,"context_line":"  ** Drastic changes in API consumer workflow"},{"line_number":25,"context_line":"* Y when you make any change to the API. Note that this includes"},{"line_number":26,"context_line":"  semantic changes which may not affect the input or output formats or"},{"line_number":27,"context_line":"  even originate in the API code layer. We are not distinguishing"},{"line_number":28,"context_line":"  between backwards compatible and backwards incompatible changes in"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da6ed579_762f4788","line":25,"in_reply_to":"da6ed579_7b43cb42","updated":"2016-01-14 18:57:56.000000000","message":"\"Y should change when\"","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"47a8817fa2f95c25ff0f7492dfaf5d605c4bea81","unresolved":false,"context_lines":[{"line_number":22,"context_line":"  cases."},{"line_number":23,"context_line":"  ** A number of endpoints get replaced by others"},{"line_number":24,"context_line":"  ** Drastic changes in API consumer workflow"},{"line_number":25,"context_line":"* Y when you make any change to the API. Note that this includes"},{"line_number":26,"context_line":"  semantic changes which may not affect the input or output formats or"},{"line_number":27,"context_line":"  even originate in the API code layer. We are not distinguishing"},{"line_number":28,"context_line":"  between backwards compatible and backwards incompatible changes in"},{"line_number":29,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":30,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":31,"context_line":"  is a backwards incompatible one."},{"line_number":32,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"da6ed579_16912b47","line":29,"range":{"start_line":25,"start_character":41,"end_line":29,"end_character":24},"updated":"2016-01-14 18:57:56.000000000","message":"Not sure I understand this correctly... Does this mean that every patch submitted to the project should/could bump up the minor version?\n\n\nCould you please let me know why you wouldn\u0027t agree with the nova, ironic, manila, ... spec for this?\n\n\n[1] http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion\n[2] https://github.com/openstack/manila/blob/master/doc/source/devref/api_microversion_dev.rst#when-do-i-need-a-new-microversion","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"4f2f9ebfd9a473b1b62acc2567b4c0c736436493","unresolved":false,"context_lines":[{"line_number":22,"context_line":"  cases."},{"line_number":23,"context_line":"  ** A number of endpoints get replaced by others"},{"line_number":24,"context_line":"  ** Drastic changes in API consumer workflow"},{"line_number":25,"context_line":"* Y when you make any change to the API. Note that this includes"},{"line_number":26,"context_line":"  semantic changes which may not affect the input or output formats or"},{"line_number":27,"context_line":"  even originate in the API code layer. We are not distinguishing"},{"line_number":28,"context_line":"  between backwards compatible and backwards incompatible changes in"},{"line_number":29,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":30,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":31,"context_line":"  is a backwards incompatible one."},{"line_number":32,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"bae84128_7129e289","line":29,"range":{"start_line":25,"start_character":41,"end_line":29,"end_character":24},"in_reply_to":"5a5ae5dd_14fc823d","updated":"2016-02-23 21:38:09.000000000","message":"Nice point, will add it as TODO for future work.","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"4f2f9ebfd9a473b1b62acc2567b4c0c736436493","unresolved":false,"context_lines":[{"line_number":22,"context_line":"  cases."},{"line_number":23,"context_line":"  ** A number of endpoints get replaced by others"},{"line_number":24,"context_line":"  ** Drastic changes in API consumer workflow"},{"line_number":25,"context_line":"* Y when you make any change to the API. Note that this includes"},{"line_number":26,"context_line":"  semantic changes which may not affect the input or output formats or"},{"line_number":27,"context_line":"  even originate in the API code layer. We are not distinguishing"},{"line_number":28,"context_line":"  between backwards compatible and backwards incompatible changes in"},{"line_number":29,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":30,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":31,"context_line":"  is a backwards incompatible one."},{"line_number":32,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"bae84128_ce23efbb","line":29,"range":{"start_line":25,"start_character":41,"end_line":29,"end_character":24},"in_reply_to":"da6ed579_16912b47","updated":"2016-02-23 21:38:09.000000000","message":"\u003e Could you please let me know why you wouldn\u0027t agree with the nova, ironic, manila, ... spec for this?\n\nnova\u0027s one is the original and I guess the other projects\u0027 ones were copied from nova and the difference happens due to unsync after the copying.","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":12053,"name":"Hua Wang","email":"wanghua.humble@gmail.com","username":"humble00"},"change_message_id":"f1acf770a7f2b06eec31a39af72e2398f96f9e8e","unresolved":false,"context_lines":[{"line_number":22,"context_line":"  cases."},{"line_number":23,"context_line":"  ** A number of endpoints get replaced by others"},{"line_number":24,"context_line":"  ** Drastic changes in API consumer workflow"},{"line_number":25,"context_line":"* Y when you make any change to the API. Note that this includes"},{"line_number":26,"context_line":"  semantic changes which may not affect the input or output formats or"},{"line_number":27,"context_line":"  even originate in the API code layer. We are not distinguishing"},{"line_number":28,"context_line":"  between backwards compatible and backwards incompatible changes in"},{"line_number":29,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":30,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":31,"context_line":"  is a backwards incompatible one."},{"line_number":32,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"5a5ae5dd_14fc823d","line":29,"range":{"start_line":25,"start_character":41,"end_line":29,"end_character":24},"in_reply_to":"da6ed579_16912b47","updated":"2016-02-03 02:15:10.000000000","message":"I think you should describe when do we need a microversion and when not in detail.","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"a4acc2a1c3f745c88d6720639c8f15116d5fa9aa","unresolved":false,"context_lines":[{"line_number":35,"context_line":"most recent versions supported. The minimum version can be increased when"},{"line_number":36,"context_line":"supporting old clients is too great a burden. Increasing the minimum version"},{"line_number":37,"context_line":"means breaking the old clients, this happens very rarely also."},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"Each version includes all the changes since minimum version was introduced."},{"line_number":40,"context_line":"It is not possible to request the feature introduced at microversion X.Y"},{"line_number":41,"context_line":"without accepting all the changes before X.Y in the same request."}],"source_content_type":"text/x-rst","patch_set":4,"id":"5a5ae5dd_19935bfc","line":38,"updated":"2016-02-03 01:41:22.000000000","message":"@Ken\u0027ichi, could you help for adding a little description about global API version, there is comment about that at line 30 https://review.openstack.org/#/c/243414/4/guidelines/microversion_specification.rst\n\nLooks like people confused on the meaning of global API version. But I think this should be describe in the versioning section.\n\nAppreciate if you can add that description, thanks!","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6824bc007e33de884b98a83672bcfdd80635626c","unresolved":false,"context_lines":[{"line_number":41,"context_line":"without accepting all the changes before X.Y in the same request."},{"line_number":42,"context_line":"For example, you cannot request the feature which is introduced at"},{"line_number":43,"context_line":"microversion 2.100 without backwards incompatible changes which are"},{"line_number":44,"context_line":"introduced before 2.100."},{"line_number":45,"context_line":""},{"line_number":46,"context_line":"Client Interaction"},{"line_number":47,"context_line":"------------------"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da6ed579_9b40ff35","line":44,"updated":"2016-01-14 11:35:51.000000000","message":"if you want to highlight the way the version numbers work you could say:\n\n...introduced at microversion 2.100 without backwards incompatible changes which were introduced in version 2.99 and earlier.","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"47a8817fa2f95c25ff0f7492dfaf5d605c4bea81","unresolved":false,"context_lines":[{"line_number":41,"context_line":"without accepting all the changes before X.Y in the same request."},{"line_number":42,"context_line":"For example, you cannot request the feature which is introduced at"},{"line_number":43,"context_line":"microversion 2.100 without backwards incompatible changes which are"},{"line_number":44,"context_line":"introduced before 2.100."},{"line_number":45,"context_line":""},{"line_number":46,"context_line":"Client Interaction"},{"line_number":47,"context_line":"------------------"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da6ed579_f6a1f746","line":44,"in_reply_to":"da6ed579_9b40ff35","updated":"2016-01-14 18:57:56.000000000","message":"+1","commit_id":"c08af4081a09e3928a7a6a8e345133019d22f3dc"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"467150ac968bf7653e95372f593d980e2a0d4e3c","unresolved":false,"context_lines":[{"line_number":16,"context_line":"Versioning of the API should be a single monotonic counter."},{"line_number":17,"context_line":"The SemVer(X.Y.Z) is a popular versioning in the world, but this microversion"},{"line_number":18,"context_line":"way is different from the SemVer one. It should be of the form X.Y where it"},{"line_number":19,"context_line":"follows the following convention:"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"* X should only be changed if a significant backwards incompatible"},{"line_number":22,"context_line":"  API change is made which affects the API as whole. That is, something"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5aef4532_1f03f574","line":19,"updated":"2016-03-07 13:50:27.000000000","message":"I think something akin to the following would be better:\n\nVersioning of the API should be single monotonic counter taking the form X.Y following these conventions:\n\n\u003cthe list\u003e\n\n.. note:: Note that these versions numbers do not follow the rules of `Semantic Versioning \u003chttp://semver.org/\u003e`_.","commit_id":"1318e138c5ea73338780ba5e0f4943e928f3aece"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"ec6448f4e043640b61b2af5967f7bbee832bb14d","unresolved":false,"context_lines":[{"line_number":16,"context_line":"Versioning of the API should be a single monotonic counter."},{"line_number":17,"context_line":"The SemVer(X.Y.Z) is a popular versioning in the world, but this microversion"},{"line_number":18,"context_line":"way is different from the SemVer one. It should be of the form X.Y where it"},{"line_number":19,"context_line":"follows the following convention:"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"* X should only be changed if a significant backwards incompatible"},{"line_number":22,"context_line":"  API change is made which affects the API as whole. That is, something"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5aef4532_7fb0398c","line":19,"in_reply_to":"5aef4532_1f03f574","updated":"2016-03-07 14:00:41.000000000","message":"+1","commit_id":"1318e138c5ea73338780ba5e0f4943e928f3aece"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"4e3db5b914a4a134368da22b446a6d90ab3812bc","unresolved":false,"context_lines":[{"line_number":16,"context_line":"Versioning of the API should be a single monotonic counter."},{"line_number":17,"context_line":"The SemVer(X.Y.Z) is a popular versioning in the world, but this microversion"},{"line_number":18,"context_line":"way is different from the SemVer one. It should be of the form X.Y where it"},{"line_number":19,"context_line":"follows the following convention:"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"* X should only be changed if a significant backwards incompatible"},{"line_number":22,"context_line":"  API change is made which affects the API as whole. That is, something"}],"source_content_type":"text/x-rst","patch_set":6,"id":"fa0719c6_2ca680c1","line":19,"in_reply_to":"5aef4532_1f03f574","updated":"2016-03-21 16:48:29.000000000","message":"Thanks for nice format, I will update it.","commit_id":"1318e138c5ea73338780ba5e0f4943e928f3aece"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"ec6448f4e043640b61b2af5967f7bbee832bb14d","unresolved":false,"context_lines":[{"line_number":45,"context_line":"without accepting all the changes before X.Y in the same request."},{"line_number":46,"context_line":"For example, you cannot request the feature which is introduced at"},{"line_number":47,"context_line":"microversion 2.100 without backwards incompatible changes which are"},{"line_number":48,"context_line":"introduced at microversion 2.100 without backwards incompatible changes"},{"line_number":49,"context_line":"which were introduced in version 2.99 and earlier."},{"line_number":50,"context_line":""},{"line_number":51,"context_line":"Client Interaction"},{"line_number":52,"context_line":"------------------"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5aef4532_fa9a97c4","line":49,"range":{"start_line":48,"start_character":29,"end_line":49,"end_character":49},"updated":"2016-03-07 14:00:41.000000000","message":"This makes for a very long confusing sentence..I think this would do.. \n\n\n    \"For example, you cannot request the feature which was introduced at\n    microversion 2.100 without backwards incompatible changes which were\n    introduced in microversion 2.99 and earlier.\"","commit_id":"1318e138c5ea73338780ba5e0f4943e928f3aece"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"4e3db5b914a4a134368da22b446a6d90ab3812bc","unresolved":false,"context_lines":[{"line_number":45,"context_line":"without accepting all the changes before X.Y in the same request."},{"line_number":46,"context_line":"For example, you cannot request the feature which is introduced at"},{"line_number":47,"context_line":"microversion 2.100 without backwards incompatible changes which are"},{"line_number":48,"context_line":"introduced at microversion 2.100 without backwards incompatible changes"},{"line_number":49,"context_line":"which were introduced in version 2.99 and earlier."},{"line_number":50,"context_line":""},{"line_number":51,"context_line":"Client Interaction"},{"line_number":52,"context_line":"------------------"}],"source_content_type":"text/x-rst","patch_set":6,"id":"fa0719c6_ecaac86f","line":49,"range":{"start_line":48,"start_character":29,"end_line":49,"end_character":49},"in_reply_to":"5aef4532_fa9a97c4","updated":"2016-03-21 16:48:29.000000000","message":"Nice sentence, it is easy to understand for me as non-native English speaker :-)","commit_id":"1318e138c5ea73338780ba5e0f4943e928f3aece"}]}