{"action":"created","issue":{"url":"https://api.github.com/repos/localForage/localForage/issues/658","repository_url":"https://api.github.com/repos/localForage/localForage","labels_url":"https://api.github.com/repos/localForage/localForage/issues/658/labels{/name}","comments_url":"https://api.github.com/repos/localForage/localForage/issues/658/comments","events_url":"https://api.github.com/repos/localForage/localForage/issues/658/events","html_url":"https://github.com/localForage/localForage/issues/658","id":204954476,"number":658,"title":"The \"version\" configuration option is not clearly documented.","user":{"login":"lddubeau","id":1963493,"avatar_url":"https://avatars3.githubusercontent.com/u/1963493?v=4","gravatar_id":"","url":"https://api.github.com/users/lddubeau","html_url":"https://github.com/lddubeau","followers_url":"https://api.github.com/users/lddubeau/followers","following_url":"https://api.github.com/users/lddubeau/following{/other_user}","gists_url":"https://api.github.com/users/lddubeau/gists{/gist_id}","starred_url":"https://api.github.com/users/lddubeau/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lddubeau/subscriptions","organizations_url":"https://api.github.com/users/lddubeau/orgs","repos_url":"https://api.github.com/users/lddubeau/repos","events_url":"https://api.github.com/users/lddubeau/events{/privacy}","received_events_url":"https://api.github.com/users/lddubeau/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":4,"created_at":"2017-02-02T18:18:59Z","updated_at":"2018-02-05T22:20:10Z","closed_at":null,"author_association":"NONE","body":"The documentation for the `version` configuration option currently states:\r\n\r\n> version\r\n> The version of your database. May be used for upgrades in the future; currently unused.\r\n\r\nThe problem is that this does not clarify whether this value is something that the client code may use. \"May be used for upgrades in the future\" does not clarify because it could mean that eventually localForage may have facilities to detect and notify client code when localForage finds an old version of the database that the client code should upgrade. Actually #117 shows that such an idea has been floated in the past. A user following this interpretation may decide to fill the field with whatever version number suits them with the idea that they'll (somehow) handle the version changes themselves for now until localForage provides some sort of formal support.\r\n\r\nHowever, upon reading the code, I see localForage has its own `onupgradeneeded` handler where it may do perform actions internal to localForage. So it seems to me that this number is something that should be used *only* if localForage's documentation says to use another value. It should be reserved for upgrades *of localForage's internal structures*, and not for upgrades to the structures accessible to the client code. I would not call it \"unused\". It is used to set the database version as understood by IndexedDB (and WebSQL, too I assume). If it were unused, I'd expect that setting it to 2, 30, or 1243 would not matter, but people setting it to such values may run into trouble later when localForage's documentation eventually states \r\n\r\n> to take advantage of localForage's new feature X, your database must be upgraded to version 2.\r\n\r\nThe poor dev who has already set it to 2 will find himself unable to upgrade, and those who are at higher values will get a warning about a downgrade and probably erratic behavior.\r\n\r\n(As a aside, an additional thing that makes me question the value of this `version` option is that it seems the `localStorage` backend simply tosses the value aside. When I look into a `localStorage` instance populated by localforage, I cannot see the version value stored anywhere. Did I miss something?)\r\n\r\nEven if my inferences are not correct above, I'd still say the role this option may play in the future is so nebulous right now that until its role is crystal-clear the documentation should not say that it is unused but instead tell users to not use it. (Or remove it from the options??)"},"comment":{"url":"https://api.github.com/repos/localForage/localForage/issues/comments/363240969","html_url":"https://github.com/localForage/localForage/issues/658#issuecomment-363240969","issue_url":"https://api.github.com/repos/localForage/localForage/issues/658","id":363240969,"user":{"login":"augbog","id":2054339,"avatar_url":"https://avatars1.githubusercontent.com/u/2054339?v=4","gravatar_id":"","url":"https://api.github.com/users/augbog","html_url":"https://github.com/augbog","followers_url":"https://api.github.com/users/augbog/followers","following_url":"https://api.github.com/users/augbog/following{/other_user}","gists_url":"https://api.github.com/users/augbog/gists{/gist_id}","starred_url":"https://api.github.com/users/augbog/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/augbog/subscriptions","organizations_url":"https://api.github.com/users/augbog/orgs","repos_url":"https://api.github.com/users/augbog/repos","events_url":"https://api.github.com/users/augbog/events{/privacy}","received_events_url":"https://api.github.com/users/augbog/received_events","type":"User","site_admin":false},"created_at":"2018-02-05T22:20:10Z","updated_at":"2018-02-05T22:20:10Z","author_association":"NONE","body":"Just curious what the status of this is?"}}
{"actor":{"display_login":"augbog"}}