{"action":"created","issue":{"url":"https://api.github.com/repos/MeteorCommunity/discussions/issues/14","labels_url":"https://api.github.com/repos/MeteorCommunity/discussions/issues/14/labels{/name}","comments_url":"https://api.github.com/repos/MeteorCommunity/discussions/issues/14/comments","events_url":"https://api.github.com/repos/MeteorCommunity/discussions/issues/14/events","html_url":"https://github.com/MeteorCommunity/discussions/issues/14","id":49858318,"number":14,"title":"Official Meteor integration directly from 3rd party libraries","user":{"login":"dandv","id":33569,"avatar_url":"https://avatars.githubusercontent.com/u/33569?v=3","gravatar_id":"","url":"https://api.github.com/users/dandv","html_url":"https://github.com/dandv","followers_url":"https://api.github.com/users/dandv/followers","following_url":"https://api.github.com/users/dandv/following{/other_user}","gists_url":"https://api.github.com/users/dandv/gists{/gist_id}","starred_url":"https://api.github.com/users/dandv/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dandv/subscriptions","organizations_url":"https://api.github.com/users/dandv/orgs","repos_url":"https://api.github.com/users/dandv/repos","events_url":"https://api.github.com/users/dandv/events{/privacy}","received_events_url":"https://api.github.com/users/dandv/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/MeteorCommunity/discussions/labels/Discussion","name":"Discussion","color":"fbca04"},{"url":"https://api.github.com/repos/MeteorCommunity/discussions/labels/Meteor%20Tool","name":"Meteor Tool","color":"5319e7"},{"url":"https://api.github.com/repos/MeteorCommunity/discussions/labels/Package%20system","name":"Package system","color":"eb6420"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":181,"created_at":"2014-11-24T05:47:33Z","updated_at":"2015-02-19T15:05:05Z","closed_at":null,"body":"If you're looking for a popular 3rd party library on Atmosphere, chances are you'll find several wrappers, in various states of maintenance. To avoid this problem, several Meteor community members have started to provide authoritative, high-quality, Meteor integrations of 3rd party libraries, complete with tests and grunt scripts. These are **forks** of the library rather than Git submodules, because forks allow modifying the source to support Meteor (if necessary) and one can still pull upstream changes without having to re-apply the integration changes.\r\n\r\nThese forks live in the [MeteorPackaging](https://github.com/orgs/MeteorPackaging) GitHub organization. This org was created so that multiple developers can collaborate on maintaining an integration in a centralized location. Now that Meteor's Package API is stable, we can submit PRs to popular JS library maintainers to add official Meteor integration. Some maintainers will accept the PR - great, we have integration straight from the source, with same-day updates on Atmosphere. Some won't accept the PR, in which case we continue with the MeteorPackaging fork.\r\n\r\nI started this effort in November 2014, [spoke about it at DevShop SF](https://www.youtube.com/watch?v=g-idz8UPtDM), and here's where we are now.\r\n\r\n## Going forward\r\n\r\nSee http://autopublish.meteor.com\r\n\r\n## Contribute (minimal effort)\r\n\r\n1. **If you're working on integrating a 3rd party library with Meteor, please post here. I have also reserved Meteor Developer (Atmosphere) organization namespaces for many libraries; ask if you need one.**\r\n2. If you have created an **MD organization** for a library, please let us know. **Namespace** is precious. Currently we're looking for:\r\n  * angular\r\n  * bootstrap\r\n  * moment\r\n  * famous\r\n  * jade\r\n  * foundation\r\n  * highcharts\r\n  * stripe\r\n  * bitcoin\r\n  * crypto\r\n  * soundcloud\r\n  * twilio ([squatted and never used](https://atmospherejs.com/?q=twilio))\r\n  * echo ([squatted](https://atmospherejs.com/echo) and [never used](https://atmospherejs.com/?q=echo))\r\n  * win (for win.js)\r\n  * app (for app.js)\r\n\r\n  Who has these?\r\n\r\n## Popular libraries  with official Meteor support\r\n\r\n* :white_check_mark: [d3](https://github.com/mbostock/d3/pull/2130) - [make, export file]\r\n* :white_check_mark: [Bootstrap Material Design](https://github.com/FezVrasta/bootstrap-material-design) by @FezVrasta. **Use [the PR](https://github.com/FezVrasta/bootstrap-material-design/pull/291) as a template.**\r\n* :white_check_mark: [Sortable](https://github.com/RubaXa/Sortable/pull/115) [first merged!]\r\n* :white_check_mark: [Keypress](https://github.com/dmauro/Keypress/pull/63) [merged 2014-11-28]\r\n* :white_check_mark: [KeyboardJS](https://github.com/RobertWHurst/KeyboardJS/pull/78) [export file]\r\n* :white_check_mark: [summernote](https://atmospherejs.com/summernote/summernote) - WYSIWYG editor; [2014-11-28]\r\n* :watch: [Semantic UI](https://github.com/Semantic-Org/Semantic-UI/issues/1298) [discussion in progress]\r\n\r\n### PR acceptance pending\r\n* :clock1: [Mousetrap](https://github.com/ccampbell/mousetrap/pull/237) -  keyboard events library [pending] [grunt, export file]\r\n* :clock10: [Font Awesome](https://github.com/FortAwesome/Font-Awesome/pull/5062#issuecomment-64947320) - [acknowledged]. Great example of Meteor resolving CSS URL paths correctly.\r\n* :ballot_box_with_check: [Moment](https://github.com/moment/moment/pull/2059) [merged in develop, [published](atmospherejs.com/momentjs/moment)]\r\n* :clock1: [Isotope](https://github.com/metafizzy/isotope/pull/829) [pending] [grunt, export file]\r\n* :clock930: [jsPlumb](https://github.com/sporritt/jsPlumb/pull/294) [pending, maintainer was in a [pissed](https://github.com/sporritt/jsPlumb/pull/291) [off](https://github.com/sporritt/jsPlumb/pull/292) [mood](https://github.com/sporritt/jsPlumb/pull/290) today]\r\n* :clock8: [Hammer](https://github.com/hammerjs/hammer.js/pull/724) - multi-touch library, ~10k GitHub stars [pending, author has changed jobs] [grunt, export file]. **Use it as a template.**\r\n\r\n### Refused to accept the PR\r\n* :no_entry_sign: [keymaster](https://github.com/madrobby/keymaster/pull/140)\r\n* :no_entry_sign: [Bootstrap](https://github.com/twbs/bootstrap/pull/15376#issuecomment-72133289) - with much love and offering a Tweet\r\n\r\n## How to do this\r\n\r\n### Overview\r\n\r\n1. Post here asking @dandv and @splendido to add you to the [MeteorPackaging organization](https://github.com/orgs/MeteorPackaging) and mention the library/libraries you want to package.\r\n2. We'll fork the library's repo into MeteorPackacing and grant you access\r\n3. Add the Meteor integration files,\r\n   * package.js\r\n   * tests\r\n   * gruntfile (or [makefile](https://github.com/mbostock/d3/pull/2130/files#diff-2) or equivalent) entries to run `meteor publish`\r\n4. publish the package to Atmosphere yourself (this is very important)\r\n5. submit a PR with the changes to the original library author (optional), or just notify them to get some exposure (they may offer to tweet about the integration or otherwise announce it)\r\n\r\nBelow are the detailed steps.\r\n\r\n### Get the integration working before even contacting the maintainer\r\n\r\n1. Fork <repo_url_of_the_library>\r\n2. `git clone <your_fork_url>`\r\n2. `cd <repo_directory>`\r\n3. `git remote add upstream <repo_url_of_the_library>`\r\n4. `git fetch upstream`\r\n5. Read through CONTRIBUTING.md or README.md and figure out which branch the original author wants pull requests against. Some can be [very finicky](https://github.com/sporritt/jsPlumb/pull/291#issuecomment-64527313).\r\n6. `git checkout -b meteor-integration upstream/`that_branch\r\n7. Create a `meteor` directory in the root of the project and copy there the [Hammer.js Meteor package files](https://github.com/MeteorPackaging/hammer.js/commit/80d10efb1627174851c1f25137fe648529ba57dc), or [the Font Awesome Meteor package files](https://github.com/dandv/Font-Awesome/tree/meteor-integration-5.0.0/meteor), depending on whether you integrate a library or CSS/image/font resources.\r\n8. Go through every file and make changes to reflect the actual library you're working on.\r\n  * in particular, give a *GOOD* summary in `package.js` (for SEO on Atmosphere), instead of the library's tagline. Example:\r\n\r\n    > Mousetrap is a simple library for handling keyboard shortcuts in Javascript.\r\n\r\n    For Atmosphere, a repository of JavaScript libraries, this is suboptimal: it repeats the library name, and it says \"library\" and \"JavaScript\" (well duh). You only have 100 characters. Don't waste them. Better:\r\n    > \"Mousetrap (official): bind, trigger and handle keyboard events on keys, combinations and sequences\"\r\n\r\n9. Export the library global(s)\r\n  1. If the package is a jQuery package and adds itself to `$`, there's [nothing to export](https://github.com/dandv/summernote/blob/meteor-integration/meteor/package.js#L20).\r\n  1. Otherwise, add a `meteor/export.js file` like [this](https://github.com/MeteorPackaging/hammer.js/blob/master/meteor/export.js):\r\n\r\n    ```js\r\n/*global Hammer:true*/  // Meteor creates a file-scope global for exporting. This comment prevents a potential JSHint warning.\r\nHammer = window.Hammer;\r\ndelete window.Hammer;\r\n```\r\n\r\n10. Add a package test file, at least checking if the library instantiates correctly.\r\n\r\n11. You want to make it as painless as possible for the maintainer to accept the PR. If there's a build process they use to publish, it would be great if you could add to it. Here's a [gruntfile patch for Meteor](https://github.com/MeteorPackaging/grunt-meteor) and a [Makefile patch](https://github.com/mbostock/d3/pull/2130/files#diff-2) (used for d3). If their README mentions Component/Bower/Npm, add a section mentioning Meteor ([example](https://github.com/dandv/Font-Awesome/commit/a4179830e9e02373d02109d97adad13b03683d95#diff-04c6e90faac2675aa89e2176d2eec7d8R68)).\r\n\r\n12. Run the tests using the build process, e.g. `grunt meteor-test`. If you want to run tests manually, execute this:\r\n\r\n        cp meteor/package.js .\r\n        spacejam --mongo-url mongodb:// test-packages ./\r\n\r\n### Pick a namespace and publish the package under it\r\n\r\n**Please be very careful with this, as renaming packages is impossible.**\r\n\r\nLog into your Meteor Developer account and create an organization that represents the package. Most often it will be the name of library, without any special characters (no `-`, `.`). No need to include the `JS` part, since we're always dealing with JavaScript libraries.\r\n\r\nIf the organization name is not available, contact me, @dandv. I've registered a bunch of them, so [potentially evil individuals](https://github.com/percolatestudio/atmosphere/issues/297#issuecomment-64600425) don't :)\r\n\r\n13. `meteor publish` the package to Atmosphere for the first time. This prevents the maintainer from running into an error that the package doesn't exist when they publish (meteor would complain about a `--create flag`).\r\n\r\n14. *After* you've ensured publishing works (namespace is available, the `name` in `package.js` is valid etc.), push to your git fork:\r\n\r\n        git commit\r\n        git push origin meteor-integration\r\n\r\n15. Congratulations! Reply to this issue and add the link to the package's Atmosphere page.\r\n\r\nNow you can go to the GitHub page of the library and issue a pull request!\r\n\r\n### Contact the library maintainers\r\n\r\n[Here is the recommended PR message](https://github.com/hammerjs/hammer.js/pull/724).\r\n\r\nSee d3 and Font Awesome above for addressing objections.\r\n\r\n### Contact the maintainers of *other* Meteor wrapper libraries\r\n\r\n1. Ask them to deprecate the library by creating a PR overwriting the README.md of their package with the text\r\n\r\n    ```text\r\nThis package is now deprecated. Please use the official Meteor integration package:\r\n\r\nhttp://atmospherejs.com/<org>/<package>\r\n```\r\n\r\n  The **commit message** should be \"Deprecating package in favor of official integration\".\r\n\r\n  The **name** of the PR issue (after you click \"Create pull request) should be \"Kind request to deprecate package in favor of official integration\".\r\n\r\n  The **text** of the PR should be similar to [this](https://github.com/pfafman/meteor-font-awesome-4/pull/2):\r\n\r\n    ```text\r\nHi X,\r\n\r\nThanks for publishing this package. In the meantime an\r\n[official Meteor integration](https://atmospherejs.com/<namespace>/<package>)\r\nhas become available.\r\n\r\nWould you like to support the official package?\r\n\r\nIf so, you can hide [your package](<atmosphere_link_to_their_package>)\r\nfrom Atmosphere searches, while still keeping it installable by apps and dependent\r\npackages, by running the following command:\r\n\r\n        meteor admin set-unmigrated <their_full:package_name>\r\n\r\nThank you,\r\nThe [Meteor official integations team](https://github.com/raix/Meteor-community-discussions/issues/14)\r\n```\r\n\r\n2. Go to the Atmosphere page of their package and flag it anyway. Ideally, get others to flag the wrapper package. This is important because [`meteor` doesn't warn the user when running `meteor add` on a deprecated package](https://github.com/raix/Meteor-community-discussions/issues/17), so we hope users will check on Atmosphere. However, each package needs several flags from different users, in order to show as flagged globally.\r\n\r\n## TODO\r\n\r\n* figure out namespacing exactly. Ideally we'd have an MD organization with the library name, and ask the library maintainers to create MD accounts reflecting their GitHub usernames. **Problem**: \r\n  * sometimes the names are taken, e.g. `moment` (pinging @estark37)\r\n  * sometimes the maintainer uses their name as the organization, and you can't have an org and individual with the same name on MD - e.g. RubaXa/Sortable\r\n  * rarely, several libraries have the same name, e.g. RubaXa/Sortable and voidberg/html5sortable (contrived example, need a better one)"},"comment":{"url":"https://api.github.com/repos/MeteorCommunity/discussions/issues/comments/75066571","html_url":"https://github.com/MeteorCommunity/discussions/issues/14#issuecomment-75066571","issue_url":"https://api.github.com/repos/MeteorCommunity/discussions/issues/14","id":75066571,"user":{"login":"splendido","id":6148980,"avatar_url":"https://avatars.githubusercontent.com/u/6148980?v=3","gravatar_id":"","url":"https://api.github.com/users/splendido","html_url":"https://github.com/splendido","followers_url":"https://api.github.com/users/splendido/followers","following_url":"https://api.github.com/users/splendido/following{/other_user}","gists_url":"https://api.github.com/users/splendido/gists{/gist_id}","starred_url":"https://api.github.com/users/splendido/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/splendido/subscriptions","organizations_url":"https://api.github.com/users/splendido/orgs","repos_url":"https://api.github.com/users/splendido/repos","events_url":"https://api.github.com/users/splendido/events{/privacy}","received_events_url":"https://api.github.com/users/splendido/received_events","type":"User","site_admin":false},"created_at":"2015-02-19T15:05:04Z","updated_at":"2015-02-19T15:05:04Z","body":"This was suggested by @mitar a couple of weeks ago, but I missed it at that time:\r\nhttps://github.com/meteor/meteor/issues/3681\r\n\r\nit seems there's a `bare` (undocumented) option that can be used (for 'web' targets only) to change/bypass the closure used to bring in package code.\r\n\r\nMight be useful for old libraries\r\n...but can to nothing for **modern** browserify packagings :("}}