{"action":"created","issue":{"url":"https://api.github.com/repos/SciTools/iris/issues/1999","repository_url":"https://api.github.com/repos/SciTools/iris","labels_url":"https://api.github.com/repos/SciTools/iris/issues/1999/labels{/name}","comments_url":"https://api.github.com/repos/SciTools/iris/issues/1999/comments","events_url":"https://api.github.com/repos/SciTools/iris/issues/1999/events","html_url":"https://github.com/SciTools/iris/pull/1999","id":152829586,"number":1999,"title":"Userguide section and whitepaper on user change management.","user":{"login":"pp-mo","id":2089069,"avatar_url":"https://avatars.githubusercontent.com/u/2089069?v=3","gravatar_id":"","url":"https://api.github.com/users/pp-mo","html_url":"https://github.com/pp-mo","followers_url":"https://api.github.com/users/pp-mo/followers","following_url":"https://api.github.com/users/pp-mo/following{/other_user}","gists_url":"https://api.github.com/users/pp-mo/gists{/gist_id}","starred_url":"https://api.github.com/users/pp-mo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pp-mo/subscriptions","organizations_url":"https://api.github.com/users/pp-mo/orgs","repos_url":"https://api.github.com/users/pp-mo/repos","events_url":"https://api.github.com/users/pp-mo/events{/privacy}","received_events_url":"https://api.github.com/users/pp-mo/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":6,"created_at":"2016-05-03T17:24:55Z","updated_at":"2016-05-06T17:22:34Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/SciTools/iris/pulls/1999","html_url":"https://github.com/SciTools/iris/pull/1999","diff_url":"https://github.com/SciTools/iris/pull/1999.diff","patch_url":"https://github.com/SciTools/iris/pull/1999.patch"},"body":"Suggestions for clarifying change management from the user POV\r\n = releases + versions, deprecations, iris.FUTURE\r\n\r\nThis is mostly for discussion at this point.\r\nIt is now pretty much complete + correct to my original conception.\r\nHowever, @rhattersley already suggested that this information might with advantage be a bit \"generalised\" and then \"pushed back\" onto the SemVer project https://github.com/mojombo/semver.\r\nAs I was most of the way toward providing this a standalone Iris docs, I've just carried on with that for this first draft. \r\n\r\nThis issue is mentioned as a possible for 1.10, #1948 \r\nwhich would be nice as we are targetting a lot of deprecations in 1.10.\r\nWhile may be relevant there, it certainly isn't essential.\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/SciTools/iris/issues/comments/217504397","html_url":"https://github.com/SciTools/iris/pull/1999#issuecomment-217504397","issue_url":"https://api.github.com/repos/SciTools/iris/issues/1999","id":217504397,"user":{"login":"pp-mo","id":2089069,"avatar_url":"https://avatars.githubusercontent.com/u/2089069?v=3","gravatar_id":"","url":"https://api.github.com/users/pp-mo","html_url":"https://github.com/pp-mo","followers_url":"https://api.github.com/users/pp-mo/followers","following_url":"https://api.github.com/users/pp-mo/following{/other_user}","gists_url":"https://api.github.com/users/pp-mo/gists{/gist_id}","starred_url":"https://api.github.com/users/pp-mo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pp-mo/subscriptions","organizations_url":"https://api.github.com/users/pp-mo/orgs","repos_url":"https://api.github.com/users/pp-mo/repos","events_url":"https://api.github.com/users/pp-mo/events{/privacy}","received_events_url":"https://api.github.com/users/pp-mo/received_events","type":"User","site_admin":false},"created_at":"2016-05-06T17:22:34Z","updated_at":"2016-05-06T17:22:34Z","body":"@rhattersley suggested I could consider pushing some of this content back into the SemVer document.\r\nSo I thought about what here is SemVer and what not.\r\n\r\nMy conclusions are...\r\n\r\nThe SemVer provisions:\r\n * backwards-incompatible changes can only occur at major releases\r\n * deprecations can only be introduced at a minor release (not bugfix)\r\n * API additions and changes can only be introduced at a minor release (not bugfix)\r\n * API means \"public\"\r\n * there are no definitions of certain terms used :\r\n  * API\r\n  * public\r\n  * behavior / functionality\r\n  * deprecation (what \"marking API functionality as deprecated\" exactly means)\r\n\r\nAdditional provisions from Iris (as I'm attempting to rationalise them):\r\n * key certainties we are adding:\r\n   * **only** deprecated features may be changed at a major release\r\n   * deprecated functionality will **always** emit runtime deprecation warnings\r\n     * ( for user code that 'could' invoke deprecated functionality, e.g. with different data )\r\n   * (\"therefore\":) code that ran in the version preceding a major release, without deprecation warnings, will continue to function unchanged\r\n * deprecations\r\n   * will always involve documentation\r\n   * will always raise runtime warnings for code where it 'could' make a difference\r\n     * ( though it still isn't clear to me whether we can *always* deliver this )\r\n * iris.FUTURE : central control for compatibility-breaking modal changes\r\n * terms we are trying to define more precisely :\r\n   * what public API means\r\n   * 'backwards compatible' means any conceivable existing code should behave as before\r\n   * what 'behaviour' means\r\n     * ( return values and side effects, but somewhat limited : excluding warnings and printed output, possibly ? )\r\n"}}