Home

This is a quick guide for integrating 3rd party libraries "officially" as a Meteor Package.

Aims

Eventually get one single official Meteor package for each popular 3rd party library which is automatically kept up to date with the latest release of the library.

How

The library should be forked in the MeteorPackaging organization, and a lean PR should be created that adds Meteor integration. Optionally, that pull request could be made against the upstream repo of the original library, in case the author wants to integrate Meteor support in their repo.

We want to eventually get the repository enabled on autopublish.meteor.com together with a working webhook!

Step by Step Guide

1. File an issue in MeteorPackaging/discussions and ask for permission to fork the repo into the MeteorPackaging org. CC @dandv or @splendido if urgent.
2. Fork the 3rd party library repo in the MeteorPackaging org.
3. Clone the forked repo locally to your machine.
4. cd <repo>; git remote add upstream <repo_url_of_the_library>
5. git fetch upstream
6. Read CONTRIBUTING.md and identify which branch is used for development (might be master, devel, next, future, etc...). Usually it is the one with more recent commits.
7. Create a new meteor-integration branch starting from the one identified above: git checkout -b meteor-integration remotes/upstream/devel.
8. Identify the build system in use (which is usually leveraged to keep files like bower.json, composer.json, and component.json up to date with new releases): grunt, gulp, make etc.
9. Hook into it to automatically generate the package.js file needed for meteor publish. For actual examples you can have a look at one of the [existing PRs] (https://github.com/MeteorPackaging/autopublish.meteor.com/wiki/Known-Attempts-to-get-Official-Integration).
   For grunt: Add your package.js file to grunt.initConfig 's replace or equivalent in Gruntfile.js

// configure the tasks
grunt.initConfig({

  ...

  // Text Replace
  replace: {
    version: { // Does not edit README.md
      src: [
        'bower.json',
        'package.json',
        'package.js',
        'jade/**/*.html'
      ],
      overwrite: true,
      replacements: [{
        from: grunt.option( "oldver" ),
        to: grunt.option( "newver" )
      }]
    },
  ...

and make sure this task is registered

// define the tasks
grunt.registerTask(
 'release',[
   'copy',
   'sass:expanded',
   'sass:min',
   'concat:dist',
   'uglify:dist',
   'usebanner:release',
   'compress:main',
   'compress:src',
   'compress:starter_template',
   'compress:parallax_template',
   'replace:version',
   'replace:readme',
   'rename:rename_src',
   'rename:rename_compiled'
 ]
);

10. Figure out which files to add in the package.js file. Don't add the minified or uglified files because Meteor already does that during bundling. Look for dist type files instead.

• Give a GOOD summary in package.js (for SEO on Atmosphere), instead of the library's tagline. Example:

  Mousetrap is a simple library for handling keyboard shortcuts in Javascript.

  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:

  "Mousetrap (official): bind, trigger and handle keyboard events on keys, combinations and sequences"

11. Test the modified build system, while making sure the package.js file is copied or symlinked in the root directory of the project.
12. Test the package locally with a simple test app. (Create a packages directory in the test app, and symlink the local package directory under it.)
13. Consider some known caveats.
14. meteor publish --create the new package to Atmosphere (there should already be a package.js file, created with step 9). See Users and Organizations below.
15. Commit the changes to the meteor-integration branch (the commit message might be Meteor integration): please try to do it with a single commit since this might help reviewers to cherry-pick it for testing!
16. Push the new branch to the MeteorPackaging fork: git push origin meteor-integration
17. Create a new pull request against the development branch in the upstream repo, asking to merge the meteor-integration branch from the forked repo. See this template PR text.
18. Add a reference to the newly created PR on this page, taking care to update its status over time.

For more detailed instructions, see the original "How to do this" section in the "Official Meteor integrations" thread. If you see something that should be added to this wiki, please file an issue.

Users and Organizations

At the moment we need the meteorpublish user to be registered among the maintainers of the package to be published in order for the procedure used by autopublish.meteor.com to work.

So when starting a new integration attempt you should do the following:

0. Log into your Meteor Developer account at http://meteor.com.
1. Register a new organization with a name sounding as official as possible, i.e. close to the library's name. If the name is already taken, contact @dandv to be transferred control.
2. Go to http://atmospherejs.com/<organizationname> and edit its profile, adding the name, description, Twitter, GitHub and website.

• Please add a detailed description of the organization. Bad: "Charts with d3". Good: "Re-usable, customizable charts and chart components for d3.js without taking away the power that d3.js gives you"

3. Add meteorpublish to the organization's team
4. Add also other users that might be willing to participate in keeping the package monitored and up to date (e.g., official library maintainers, other users which used to have old wrapper packages for the same library, etc.)
5. As a courtesy and in case you get hit by a bus, please add @dandv and @splendido to the organization as well.