{"action":"created","issue":{"url":"https://api.github.com/repos/rackspace/rack/issues/294","labels_url":"https://api.github.com/repos/rackspace/rack/issues/294/labels{/name}","comments_url":"https://api.github.com/repos/rackspace/rack/issues/294/comments","events_url":"https://api.github.com/repos/rackspace/rack/issues/294/events","html_url":"https://github.com/rackspace/rack/issues/294","id":101453553,"number":294,"title":"versioning services in commands","user":{"login":"jrperritt","id":1733222,"avatar_url":"https://avatars.githubusercontent.com/u/1733222?v=3","gravatar_id":"","url":"https://api.github.com/users/jrperritt","html_url":"https://github.com/jrperritt","followers_url":"https://api.github.com/users/jrperritt/followers","following_url":"https://api.github.com/users/jrperritt/following{/other_user}","gists_url":"https://api.github.com/users/jrperritt/gists{/gist_id}","starred_url":"https://api.github.com/users/jrperritt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jrperritt/subscriptions","organizations_url":"https://api.github.com/users/jrperritt/orgs","repos_url":"https://api.github.com/users/jrperritt/repos","events_url":"https://api.github.com/users/jrperritt/events{/privacy}","received_events_url":"https://api.github.com/users/jrperritt/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-08-17T15:54:28Z","updated_at":"2015-08-17T16:25:39Z","closed_at":null,"body":"When Rackspace decides to upgrade to a new version of a service, there will be a period of time when we will have to support 2 versions of a service. Below are some options to handle this:\r\n\r\n1. Add a new `version` word in the 3rd position of the command: `rack servers v2 instance list`\r\n\r\n2. Append the version to the service: `rack servers-v2 instance list`\r\n\r\n3. Try to handle the command for the user with the currently-supported API  and fallback to the recently-deprecated API.\r\n\r\nIn my opinion, `1` is the cleanest but the most disruptive. It would require users to type and additional word in the command, while also having to know which version they want.\r\n\r\n`2` would also require users to know which version they want, but would remove the extra word from the command.\r\n\r\n`3` is the least disruptive, but the most taxing on the code base. Basically, it would amount to supporting all the possible sub-services (and flags per sub-service) for both versions of the service, and then trying to figure out based on the flags provided which one the user wants. In addition, having that logic in the codebase will be short-lived since after the grace period for supporting both versions is over, there'll be no need to keep it around. Though this option sounds like the best for users, it's really masking something they should be in control of.\r\n\r\nOther attempts I can think of to solve this problem seem inconsistent. Namely:\r\n\r\n1. Allowing for an optional version. As in, hypothetically, both `rack servers-v2 instance list` and `rack servers instance list` would work. Presumably the version-less command would point to the current service endpoint, but would change suddenly without warning over time.\r\n\r\nThoughts?"},"comment":{"url":"https://api.github.com/repos/rackspace/rack/issues/comments/131879201","html_url":"https://github.com/rackspace/rack/issues/294#issuecomment-131879201","issue_url":"https://api.github.com/repos/rackspace/rack/issues/294","id":131879201,"user":{"login":"jrperritt","id":1733222,"avatar_url":"https://avatars.githubusercontent.com/u/1733222?v=3","gravatar_id":"","url":"https://api.github.com/users/jrperritt","html_url":"https://github.com/jrperritt","followers_url":"https://api.github.com/users/jrperritt/followers","following_url":"https://api.github.com/users/jrperritt/following{/other_user}","gists_url":"https://api.github.com/users/jrperritt/gists{/gist_id}","starred_url":"https://api.github.com/users/jrperritt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jrperritt/subscriptions","organizations_url":"https://api.github.com/users/jrperritt/orgs","repos_url":"https://api.github.com/users/jrperritt/repos","events_url":"https://api.github.com/users/jrperritt/events{/privacy}","received_events_url":"https://api.github.com/users/jrperritt/received_events","type":"User","site_admin":false},"created_at":"2015-08-17T16:25:39Z","updated_at":"2015-08-17T16:25:39Z","body":"That's a good idea. Then we'd only need to figure out the best way of communicating that the new release uses a new version of the service. Maybe a blog post and/or release notes are good enough.\r\n\r\nNote though that we're exclusively talking about major version changes (2 -> 3 and not 2.1 -> 2.2). Changes to the minor could be added without issue. For the Cloud Control panel, many things are handled for the user behind the scenes. If they (or anyone else) were to offer 2 different major versions of a service, they'd handle it similar to `3` above."}}