{"action":"created","issue":{"url":"https://api.github.com/repos/lytics/ember-data-model-fragments/issues/189","repository_url":"https://api.github.com/repos/lytics/ember-data-model-fragments","labels_url":"https://api.github.com/repos/lytics/ember-data-model-fragments/issues/189/labels{/name}","comments_url":"https://api.github.com/repos/lytics/ember-data-model-fragments/issues/189/comments","events_url":"https://api.github.com/repos/lytics/ember-data-model-fragments/issues/189/events","html_url":"https://github.com/lytics/ember-data-model-fragments/pull/189","id":142847161,"number":189,"title":"First pass at updating the README.md to match the new addonify patterns.","user":{"login":"workmanw","id":825487,"avatar_url":"https://avatars.githubusercontent.com/u/825487?v=3","gravatar_id":"","url":"https://api.github.com/users/workmanw","html_url":"https://github.com/workmanw","followers_url":"https://api.github.com/users/workmanw/followers","following_url":"https://api.github.com/users/workmanw/following{/other_user}","gists_url":"https://api.github.com/users/workmanw/gists{/gist_id}","starred_url":"https://api.github.com/users/workmanw/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/workmanw/subscriptions","organizations_url":"https://api.github.com/users/workmanw/orgs","repos_url":"https://api.github.com/users/workmanw/repos","events_url":"https://api.github.com/users/workmanw/events{/privacy}","received_events_url":"https://api.github.com/users/workmanw/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":4,"created_at":"2016-03-23T03:20:09Z","updated_at":"2016-03-24T15:58:25Z","closed_at":"2016-03-24T15:14:41Z","pull_request":{"url":"https://api.github.com/repos/lytics/ember-data-model-fragments/pulls/189","html_url":"https://github.com/lytics/ember-data-model-fragments/pull/189","diff_url":"https://github.com/lytics/ember-data-model-fragments/pull/189.diff","patch_url":"https://github.com/lytics/ember-data-model-fragments/pull/189.patch"},"body":"I'm submitting this as a PR to the addonify branch so that @slindberg and @jakesjews can review it. Here is a link to the [rendered view](https://github.com/workmanw/ember-data-model-fragments/blob/d15613cf9d62c30e604dc08d5031adeddc7e975a/README.md).\r\n\r\nThere are two things I specifically wanted to get feedback on. \r\n\r\n1. Since I've upgraded the docs to use the newish ES6 model pattern (rather than globals) the examples tend to have more files. See [here](https://github.com/workmanw/ember-data-model-fragments/blob/d15613cf9d62c30e604dc08d5031adeddc7e975a/README.md#example). I added the name of the model as a path based code comment at the top of each snippet. This is what many addons do, include the official ember model guides. My question is, is that clear enough for someone reading it? If not, I think a good alternative would be to make a variable, we do this in our app. Eg.\r\n\r\n    ```javascript\r\n    // app/models/person.js\r\n    import Model from 'ember-data/model';\r\n    import {\r\n      fragment,\r\n      fragmentArray,\r\n      array\r\n    } from 'model-fragments/attributes';\r\n\r\n    let PersonModel = Model.extend({\r\n      name      : fragment('name'),\r\n      addresses : fragmentArray('address'),\r\n      titles    : array()\r\n    });\r\n\r\n    export default PersonModel;\r\n    ```\r\n\r\n2. `fragment` and `Fragment` look kind of ambiguous in the documentation. If you didn't catch the difference, the former is the attribute marco while the later is the model class. Just looking at it, it seems ripe for confusion. Perhaps I should change `fragment` to `fragmentAttr`? But then what about `fragmentArray` and `array`, would you call them `fragmentArrayAttr` and `arrayAttr` respectfully? Thoughts?\r\n\r\nTODO:\r\n- [x] We probably don't need to meantion `ember build` any more.\r\n- [x] Document how to use `testem` and `ember try:testall`."},"comment":{"url":"https://api.github.com/repos/lytics/ember-data-model-fragments/issues/comments/200900248","html_url":"https://github.com/lytics/ember-data-model-fragments/pull/189#issuecomment-200900248","issue_url":"https://api.github.com/repos/lytics/ember-data-model-fragments/issues/189","id":200900248,"user":{"login":"slindberg","id":421506,"avatar_url":"https://avatars.githubusercontent.com/u/421506?v=3","gravatar_id":"","url":"https://api.github.com/users/slindberg","html_url":"https://github.com/slindberg","followers_url":"https://api.github.com/users/slindberg/followers","following_url":"https://api.github.com/users/slindberg/following{/other_user}","gists_url":"https://api.github.com/users/slindberg/gists{/gist_id}","starred_url":"https://api.github.com/users/slindberg/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/slindberg/subscriptions","organizations_url":"https://api.github.com/users/slindberg/orgs","repos_url":"https://api.github.com/users/slindberg/repos","events_url":"https://api.github.com/users/slindberg/events{/privacy}","received_events_url":"https://api.github.com/users/slindberg/received_events","type":"User","site_admin":false},"created_at":"2016-03-24T15:58:25Z","updated_at":"2016-03-24T15:58:25Z","body":"I think the examples are plenty clear since you can read the import directly, I'm actually more worried about removing the `DS` and `MF` namespaces from the text, since it's not obvious where they are coming from anymore. Without keeping the namespaces though, I don't what the answer is. It'd be a little weird to refer to `ember-data/Transform` or `model-fragments/Fragment`...\r\n\r\nAs for `fragment` vs. `Fragment` I agree it's not ideal, but changing either would break semver, so they are pretty locked in. :shrug:"}}