{"action":"created","issue":{"url":"https://api.github.com/repos/svaarala/duktape/issues/749","repository_url":"https://api.github.com/repos/svaarala/duktape","labels_url":"https://api.github.com/repos/svaarala/duktape/issues/749/labels{/name}","comments_url":"https://api.github.com/repos/svaarala/duktape/issues/749/comments","events_url":"https://api.github.com/repos/svaarala/duktape/issues/749/events","html_url":"https://github.com/svaarala/duktape/issues/749","id":153313495,"number":749,"title":"What 'introduced' version to use in API docs for calls with incompatible changes?","user":{"login":"svaarala","id":6377415,"avatar_url":"https://avatars.githubusercontent.com/u/6377415?v=3","gravatar_id":"","url":"https://api.github.com/users/svaarala","html_url":"https://github.com/svaarala","followers_url":"https://api.github.com/users/svaarala/followers","following_url":"https://api.github.com/users/svaarala/following{/other_user}","gists_url":"https://api.github.com/users/svaarala/gists{/gist_id}","starred_url":"https://api.github.com/users/svaarala/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/svaarala/subscriptions","organizations_url":"https://api.github.com/users/svaarala/orgs","repos_url":"https://api.github.com/users/svaarala/repos","events_url":"https://api.github.com/users/svaarala/events{/privacy}","received_events_url":"https://api.github.com/users/svaarala/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/svaarala/duktape/labels/documentation","name":"documentation","color":"eeeeee"}],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/svaarala/duktape/milestones/5","html_url":"https://github.com/svaarala/duktape/milestones/v2.0.0","labels_url":"https://api.github.com/repos/svaarala/duktape/milestones/5/labels","id":840957,"number":5,"title":"v2.0.0","description":"","creator":{"login":"svaarala","id":6377415,"avatar_url":"https://avatars.githubusercontent.com/u/6377415?v=3","gravatar_id":"","url":"https://api.github.com/users/svaarala","html_url":"https://github.com/svaarala","followers_url":"https://api.github.com/users/svaarala/followers","following_url":"https://api.github.com/users/svaarala/following{/other_user}","gists_url":"https://api.github.com/users/svaarala/gists{/gist_id}","starred_url":"https://api.github.com/users/svaarala/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/svaarala/subscriptions","organizations_url":"https://api.github.com/users/svaarala/orgs","repos_url":"https://api.github.com/users/svaarala/repos","events_url":"https://api.github.com/users/svaarala/events{/privacy}","received_events_url":"https://api.github.com/users/svaarala/received_events","type":"User","site_admin":false},"open_issues":30,"closed_issues":9,"state":"open","created_at":"2014-10-26T15:05:37Z","updated_at":"2016-05-06T16:51:15Z","due_on":null,"closed_at":null},"comments":8,"created_at":"2016-05-05T20:04:20Z","updated_at":"2016-05-06T17:15:23Z","closed_at":null,"body":"For example, `duk_safe_call()` gets a userdata argument in Duktape 2.x which is a source incompatible change. Should the call be listed as \"new in 2.0.0\" in the API documentation, i.e. it would appear in the \"2.0.0\" tag list of the api.html page?\r\n\r\nOne alternative is to keep the original introduced-version for calls where the essential semantics are the same as previously with maybe new arguments or flags, but add some metadata key indicating last incompatible change."},"comment":{"url":"https://api.github.com/repos/svaarala/duktape/issues/comments/217502604","html_url":"https://github.com/svaarala/duktape/issues/749#issuecomment-217502604","issue_url":"https://api.github.com/repos/svaarala/duktape/issues/749","id":217502604,"user":{"login":"svaarala","id":6377415,"avatar_url":"https://avatars.githubusercontent.com/u/6377415?v=3","gravatar_id":"","url":"https://api.github.com/users/svaarala","html_url":"https://github.com/svaarala","followers_url":"https://api.github.com/users/svaarala/followers","following_url":"https://api.github.com/users/svaarala/following{/other_user}","gists_url":"https://api.github.com/users/svaarala/gists{/gist_id}","starred_url":"https://api.github.com/users/svaarala/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/svaarala/subscriptions","organizations_url":"https://api.github.com/users/svaarala/orgs","repos_url":"https://api.github.com/users/svaarala/repos","events_url":"https://api.github.com/users/svaarala/events{/privacy}","received_events_url":"https://api.github.com/users/svaarala/received_events","type":"User","site_admin":false},"created_at":"2016-05-06T17:15:23Z","updated_at":"2016-05-06T17:15:23Z","body":"Documentation is not currently included in the dist package (though that would be easy to fix and it might be nice to have the static HTML files available for offline viewing etc).\r\n\r\nThe website has snapshots of documentation for earlier releases, e.g. http://duktape.org/1.0.0/api.html so the old API calls are still viewable there.\r\n\r\nI agree it'd be nice to just remove stuff that's no longer part of the API, unless there's some actual use case where that metadata matters. For example, removed calls could be part of the API documentation but labelled as such (or perhaps there could be a button \"Show removed calls\" in the future). In practical terms there's also going to be a longish period where some people will be developing/maintaining a 1.x code base while others will work with the 2.x API only - and the API documentation may need to support both use cases."}}