{"action":"created","issue":{"url":"https://api.github.com/repos/biocore/scikit-bio/issues/945","labels_url":"https://api.github.com/repos/biocore/scikit-bio/issues/945/labels{/name}","comments_url":"https://api.github.com/repos/biocore/scikit-bio/issues/945/comments","events_url":"https://api.github.com/repos/biocore/scikit-bio/issues/945/events","html_url":"https://github.com/biocore/scikit-bio/pull/945","id":87178402,"number":945,"title":"adding stability state decorators","user":{"login":"gregcaporaso","id":192372,"avatar_url":"https://avatars.githubusercontent.com/u/192372?v=3","gravatar_id":"","url":"https://api.github.com/users/gregcaporaso","html_url":"https://github.com/gregcaporaso","followers_url":"https://api.github.com/users/gregcaporaso/followers","following_url":"https://api.github.com/users/gregcaporaso/following{/other_user}","gists_url":"https://api.github.com/users/gregcaporaso/gists{/gist_id}","starred_url":"https://api.github.com/users/gregcaporaso/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gregcaporaso/subscriptions","organizations_url":"https://api.github.com/users/gregcaporaso/orgs","repos_url":"https://api.github.com/users/gregcaporaso/repos","events_url":"https://api.github.com/users/gregcaporaso/events{/privacy}","received_events_url":"https://api.github.com/users/gregcaporaso/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":{"login":"jairideout","id":1847232,"avatar_url":"https://avatars.githubusercontent.com/u/1847232?v=3","gravatar_id":"","url":"https://api.github.com/users/jairideout","html_url":"https://github.com/jairideout","followers_url":"https://api.github.com/users/jairideout/followers","following_url":"https://api.github.com/users/jairideout/following{/other_user}","gists_url":"https://api.github.com/users/jairideout/gists{/gist_id}","starred_url":"https://api.github.com/users/jairideout/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jairideout/subscriptions","organizations_url":"https://api.github.com/users/jairideout/orgs","repos_url":"https://api.github.com/users/jairideout/repos","events_url":"https://api.github.com/users/jairideout/events{/privacy}","received_events_url":"https://api.github.com/users/jairideout/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/biocore/scikit-bio/milestones/11","html_url":"https://github.com/biocore/scikit-bio/milestones/0.4.0:%20Beta%20Release","labels_url":"https://api.github.com/repos/biocore/scikit-bio/milestones/11/labels","id":802955,"number":11,"title":"0.4.0: Beta Release","description":"Initial beta release to correspond with SciPy 2015. Release includes API that is marked stable, experimental (unstable), and deprecated.","creator":{"login":"ebolyen","id":3976804,"avatar_url":"https://avatars.githubusercontent.com/u/3976804?v=3","gravatar_id":"","url":"https://api.github.com/users/ebolyen","html_url":"https://github.com/ebolyen","followers_url":"https://api.github.com/users/ebolyen/followers","following_url":"https://api.github.com/users/ebolyen/following{/other_user}","gists_url":"https://api.github.com/users/ebolyen/gists{/gist_id}","starred_url":"https://api.github.com/users/ebolyen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ebolyen/subscriptions","organizations_url":"https://api.github.com/users/ebolyen/orgs","repos_url":"https://api.github.com/users/ebolyen/repos","events_url":"https://api.github.com/users/ebolyen/events{/privacy}","received_events_url":"https://api.github.com/users/ebolyen/received_events","type":"User","site_admin":false},"open_issues":26,"closed_issues":7,"state":"open","created_at":"2014-09-25T17:43:20Z","updated_at":"2015-06-23T15:16:30Z","due_on":"2015-06-30T07:00:00Z","closed_at":null},"comments":8,"created_at":"2015-06-11T02:11:06Z","updated_at":"2015-06-23T16:22:25Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/biocore/scikit-bio/pulls/945","html_url":"https://github.com/biocore/scikit-bio/pull/945","diff_url":"https://github.com/biocore/scikit-bio/pull/945.diff","patch_url":"https://github.com/biocore/scikit-bio/pull/945.patch"},"body":"This contains a first pass at defining stability states of code in scikit-bio (#923). Our initial discussions of this happened at the UCSD skbio sprint in May, and @ebolyen and I spent some more time discussing after that resulting in [this doc](https://hackpad.com/skbio-stableexperimentaldeprecated-ideas-mRBeikR4JXX). I'm going to be offline for a few days, so wanted to get my work on this visible, but there is still more to do before merge. After merging, in a separate pull request, we'll work through the code base and define the stability state of all public functionality. \r\n\r\nI updated the state diagram to indicate the three possible states more clearly: experimental, stable, and deprecated. \r\n\r\n![image](https://cloud.githubusercontent.com/assets/192372/8098305/3717244e-0fa3-11e5-8479-92e4959738ef.png)\r\n\r\nThe docstring of the base class for these decorators describe the theory behind these. That will be ported to an easily accessible document before merge. \r\n\r\nWe ultimately decided to use decorators instead of splitting the code base into ``skbio/`` and ``skbio/experimental`` as we can achieve what we want to with these decorators with a lot less complexity for new developers. (For example, instead of having to tell people to move code to different places, define new experimental methods of stable classes as functions under ``skbio/experimental``, and so on, we can just decorate functionality.) \r\n\r\nTo-do items following code review with @ebolyen, @jairideout and @anderspitman. \r\n\r\nNext steps:\r\n - [x] How does numpydoc format deprecation warnings?\r\n - [x] ``UserWarning`` to ``DeprecationWarning``\r\n - [x] experimental ``until`` to ``as-of``\r\n - [x] deprecated should take ``as-of`` in addition to ``until``\r\n - [x] force naming of kwargs for readability\r\n - [x] update ``deprecated``'s ``wrapped_f.__name__``, etc (see [link from Evan](http://stackoverflow.com/questions/147816/preserving-signatures-of-decorated-functions))\r\n - [x] better handling of missing keys in the constructors\r\n - [x] move high-level doc to new rst (maybe under *User Documentation*)\r\n - [x] add unit tests\r\n\r\nLonger term:\r\n - ``deprecated_parameter`` (#958)\r\n - plan for deprecating full modules and subpackages (#959)\r\n\r\n "},"comment":{"url":"https://api.github.com/repos/biocore/scikit-bio/issues/comments/114562051","html_url":"https://github.com/biocore/scikit-bio/pull/945#issuecomment-114562051","issue_url":"https://api.github.com/repos/biocore/scikit-bio/issues/945","id":114562051,"user":{"login":"jairideout","id":1847232,"avatar_url":"https://avatars.githubusercontent.com/u/1847232?v=3","gravatar_id":"","url":"https://api.github.com/users/jairideout","html_url":"https://github.com/jairideout","followers_url":"https://api.github.com/users/jairideout/followers","following_url":"https://api.github.com/users/jairideout/following{/other_user}","gists_url":"https://api.github.com/users/jairideout/gists{/gist_id}","starred_url":"https://api.github.com/users/jairideout/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jairideout/subscriptions","organizations_url":"https://api.github.com/users/jairideout/orgs","repos_url":"https://api.github.com/users/jairideout/repos","events_url":"https://api.github.com/users/jairideout/events{/privacy}","received_events_url":"https://api.github.com/users/jairideout/received_events","type":"User","site_admin":false},"created_at":"2015-06-23T16:22:25Z","updated_at":"2015-06-23T16:22:25Z","body":"@gregcaporaso this looks great! I had a few comments, most should be easy to resolve."}}