{"action":"created","issue":{"url":"https://api.github.com/repos/facebook/facebook-php-sdk-v4/issues/332","labels_url":"https://api.github.com/repos/facebook/facebook-php-sdk-v4/issues/332/labels{/name}","comments_url":"https://api.github.com/repos/facebook/facebook-php-sdk-v4/issues/332/comments","events_url":"https://api.github.com/repos/facebook/facebook-php-sdk-v4/issues/332/events","html_url":"https://github.com/facebook/facebook-php-sdk-v4/issues/332","id":55687785,"number":332,"title":"[Proposal] Revisit Semantic Versioning","user":{"login":"SammyK","id":578780,"avatar_url":"https://avatars.githubusercontent.com/u/578780?v=3","gravatar_id":"","url":"https://api.github.com/users/SammyK","html_url":"https://github.com/SammyK","followers_url":"https://api.github.com/users/SammyK/followers","following_url":"https://api.github.com/users/SammyK/following{/other_user}","gists_url":"https://api.github.com/users/SammyK/gists{/gist_id}","starred_url":"https://api.github.com/users/SammyK/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/SammyK/subscriptions","organizations_url":"https://api.github.com/users/SammyK/orgs","repos_url":"https://api.github.com/users/SammyK/repos","events_url":"https://api.github.com/users/SammyK/events{/privacy}","received_events_url":"https://api.github.com/users/SammyK/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-01-27T22:59:41Z","updated_at":"2015-01-28T15:10:30Z","closed_at":null,"body":"I'm proposing we revisit yet another @yguedidi issue from a while ago #134, [Semantic Versioning](http://semver.org/).\r\n\r\n# The problem\r\n\r\nCurrently we're handling versioning like this: `4.MAJOR.MINOR|PATCH`. Both `MINOR` and `PATCH` should be backwards-compatible and `MAJOR` can contain breaking changes.\r\n\r\nWe're running into an issue like in #326 where simply changing the default Graph version will actually break BC. And updating the SDK to fit the new Graph API version (like removing `isLiked()` from `FacebookPageTabHelper`) is another BC.\r\n\r\nAnd as the SDK evolves and starts to conform more to a [ubiquitous language](http://martinfowler.com/bliki/UbiquitousLanguage.html) within Facebook's domain, these smaller name changes are often BC's as well.\r\n\r\nAnother issue that could possibly explode when we tag 4.1 stable relates to issue #268. For those who have a composer requiring `~4.0` will get the super-breaking-change from 4.0 to 4.1 as soon as 4.1 is tagged. My own `composer.json`'s were set up this way until a few months ago.\r\n\r\n# The solution\r\n\r\nSo it'd be really nice to follow SemVer's `MAJOR.MINOR.PATCH` format. And we could follow this versioning schedule:\r\n\r\n## MAJOR\r\n\r\n- When a new version of Graph is released.\r\n- Any SDK API breaking changes related to ubiquitous language or breaking refactors.\r\n\r\nWe could hold off on releasing any breaking API changes until the next Graph API version. So the SDK would follow the same versioning schedule as Graph.\r\n\r\n## MINOR\r\n\r\n- Any new feature that doesn't break BC.\r\n\r\n## PATCH\r\n\r\n- Non-breaking bug fixes.\r\n- Non-breaking security updates.\r\n\r\n# Going forward\r\n\r\nIf we follow this setup, all these huge refactors on `dev-master` would be tagged as `5.0.0` instead of `4.1.0`. Then with the next Graph version we'd roll any breaking changes on `dev-master` into `6.0.0`.\r\n\r\nThis will also help us make a very easy-to-understand `UPGRADE-5.0.md`, `UPGRADE-6.0.md` files (as pointed out is something missing from the docs in #321).\r\n\r\n# Considerations\r\n\r\nThe `-v4` suffix in the repo name needs to be addressed but I'm not 100% sure how to approach that one.\r\n\r\nThoughts? :)"},"comment":{"url":"https://api.github.com/repos/facebook/facebook-php-sdk-v4/issues/comments/71849893","html_url":"https://github.com/facebook/facebook-php-sdk-v4/issues/332#issuecomment-71849893","issue_url":"https://api.github.com/repos/facebook/facebook-php-sdk-v4/issues/332","id":71849893,"user":{"login":"yguedidi","id":1480128,"avatar_url":"https://avatars.githubusercontent.com/u/1480128?v=3","gravatar_id":"","url":"https://api.github.com/users/yguedidi","html_url":"https://github.com/yguedidi","followers_url":"https://api.github.com/users/yguedidi/followers","following_url":"https://api.github.com/users/yguedidi/following{/other_user}","gists_url":"https://api.github.com/users/yguedidi/gists{/gist_id}","starred_url":"https://api.github.com/users/yguedidi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yguedidi/subscriptions","organizations_url":"https://api.github.com/users/yguedidi/orgs","repos_url":"https://api.github.com/users/yguedidi/repos","events_url":"https://api.github.com/users/yguedidi/events{/privacy}","received_events_url":"https://api.github.com/users/yguedidi/received_events","type":"User","site_admin":false},"created_at":"2015-01-28T15:10:30Z","updated_at":"2015-01-28T15:10:30Z","body":"> When a new version of Graph is released.\r\n\r\nI think this should go in the minor part. To make this possible, I think the SDK default Graph API version should be null, ie unversionned.\r\nThen we can add new fields/nodes as new method/obects, depecate fields/node that are not part of the last Graph version. And when the default unversionned Graph API version change, we can release a new SDK major version that remove deprecated things.\r\n\r\nI don't know, if I'm understandable, I'm writing this quickly.. :)"}}