|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We're huge fans of open-source, and we absolutely love getting good contributions to **analytics.js**! Integrations are available to thousands of Segment customers and we have hundreds of integrations in already in our queue, so it's important that you do the following _before writing a pull request_. |
| 4 | + |
| 5 | +1. Read about our integration options and apply to be a partner: https://segment.com/partners/ |
| 6 | +1. Hear from the Segment team before submitting your pull request. |
| 7 | + |
| 8 | +## Getting Set Up |
| 9 | + |
| 10 | +To start, we'll get you set up with our development environment. All of our development scripts and helpers are written in [node.js](http://nodejs.org), so you'll want to install that first by going to [nodejs.org](http://nodejs.org). |
| 11 | + |
| 12 | +Then after forking **analytics.js-integrations** just `cd` into the folder and run `make`: |
| 13 | + |
| 14 | +```bash |
| 15 | +$ cd analytics.js-integration-segmentio |
| 16 | +$ make |
| 17 | +``` |
| 18 | + |
| 19 | +That will install all of our [npm](http://npmjs.org) and [component](http://component.io) dependencies and compile the latest version of the development build to test against. You can now add your changes to the library, and run `make test` to make sure everything is passing still. |
| 20 | + |
| 21 | +The commands you'll want to know for development are: |
| 22 | + |
| 23 | +```bash |
| 24 | +$ make # re-compiles the development build of analytics.js for testing |
| 25 | +$ make test # runs all of the tests in your terminal |
| 26 | +$ make test-browser # runs all of the tests in your browser, for nicer debugging |
| 27 | +``` |
| 28 | + |
| 29 | +## Writing Tests |
| 30 | + |
| 31 | +Every contribution should be accompanied by matching tests. If you look inside of the `test/` directory, you'll see we're pretty serious about this. That's because: |
| 32 | + |
| 33 | +1. **analytics.js** runs on tons of different types of browsers, operating systems, etc. and we want to make sure it runs well everywhere. |
| 34 | +1. It lets us add new features much, much more quickly. |
| 35 | +1. We aren't insane. |
| 36 | + |
| 37 | +When adding your own integration, the easiest way to figure out what major things to test is to look at everything you've added to the integration `prototype`. You'll want to write testing groups for `#initialize`, `#load`, `#identify`, `#track`, etc. And each group should test all of the expected functionality. |
| 38 | + |
| 39 | +The most important thing to writing clean, easy-to-manage integrations is to **keep them small** and **clean up after each test**, so that the environment is never polluted by an individual test. |
| 40 | + |
| 41 | +If you run into any questions, check out a few of our existing integrations to see how we've done it. |
| 42 | + |
| 43 | +## Contributing Checklist |
| 44 | + |
| 45 | +To help make contributing easy, here's all the things you need to remember: |
| 46 | + |
| 47 | +- Add your integration file to `/lib`. |
| 48 | +- Create a new Integration constructor with the `integration` factory component. |
| 49 | +- Add your integration's default options with `.option()`. |
| 50 | +- Add an `initialize` method to your integration's `prototype`. |
| 51 | +- Add methods you want to support to the `prototype`. (`identify`, `track`, `pageview`, etc.) |
| 52 | +- Write tests for all of your integration's logic. |
| 53 | +- Run the tests and get everything passing. |
| 54 | +- Commit your changes with a nice commit message. |
| 55 | +- Submit your pull request. |
0 commit comments