Contributing

Contributing

Introduction

Contributing is the best way to improve a open source project and Github makes it really easy to get started. Small introduction to the layout of Socket.IO, it's divided in to two projects:

1. The Socket.IO server for Node.js
2. The Socket.IO client for browsers

The Socket.IO server and the Socket.IO client communicate with each other using the Socket.IO protocol specification which is a light weight way of sending instructions over the established connection.

There are different ways of contributing to the Socket.IO project.

1. Report bugs for the Socket.IO client or Socket.IO server.
2. Create patches for the reported bugs
3. Improve the performance, memory usage etc.
4. Write wiki pages, like this one.
5. Helping people to get started with Socket.IO and hang out in our IRC channel (irc.freenode.net #socket.io).

Reporting

If you have found a issue you can report it in our issue trackers, for server related issues you can report them at socket.io/issues and the client bugs can be reported at socket-io-client/issues.

A good bug report should contain the following information. This will help us with finding and fixing the bug. When you report a bug always make sure it's reproducible with the latest stable version of Socket.IO. And if it's not reported before (there is a search box above the issues list).

Socket.IO help full information

1. Description of the bug.
2. Create a reproducible or failing test case (preferred) or write down the steps.
3. Make sure you test or steps only includes Socket.IO related code and does not depend on third party modules.
4. Report the Node.js version
5. If the bug is related to a transport method make sure that you tell us which transport method should be used.
6. Are you using Socket.IO cross port / cross domain.

Socket.IO Client

1. Description of the bug.
2. Create a reproducible or failing test case (preferred) or write down the steps.
3. Make sure you test or steps only includes Socket.IO related code and does not depend on third party client code.
4. Report the browser version, operating system, service packs.
5. If the bug is related to a transport method make sure that you tell us which transport method should be used.
6. Are you using Socket.IO cross port / cross domain.

Forking the code

The best way to create patches or improve the code is to fork the project on Github (see forking).

The best way to create a patch is to create a new branch in your repository where you make the changes. This allows you to create different pull requests for different issues:

git branch <branchname>
git checkout <branchname>

Where <branchname> is the name of the branch your creating. I usually name it bug/000 so I know that the branch is used to fix a bug for issue #000.

Once you have created the a patch for the issue, you should always run the test suite. There are Makefiles in the root of the repositories.

Running tests for Socket.IO

Currently the tests for Socket.IO requires you to have Redis installed and running on the default port. This is needed to test the upcoming RedisStore backend for Socket.IO

make test

This will run the unit test suite to confirm that your patch didn't break any existing functionality. When this all passes it might be smart idea to add a test against the bug you just patched to prevent it from breaking in the future. Adding tests are pretty straight forward, you can take a look at the existing test suites to see how they work. The tests are separated by the different modules and transports that Socket.IO uses.

Running the tests for Socket.IO client

There are 2 different tests on in the Socket.IO client, we have acceptance tests and a basic builder test. The builder test will test for leaking globals and makes sure that the files can still be build properly without any issues.

The acceptance tests contains unit tests for the different modules and integration tests, where we run the Socket.IO client against the Socket.IO server instance. This test should pass on all of the supported browsers.

make test

To run the builder tests.

make test-acceptance

To start the acceptance tests, you can than you can visit http://localhost:3000/ to run the test-acceptance in your browser. When all tests passes, it might be smart to add another test to the acceptance test to make sure that we won't break it in future updates.

When you add a new test you need to modify the /suppport/testrunner/app.js by adding a new server instance with the name of the tests. But you also need to add the same test name to the /test/socket.test.js so we assign that test to the correct server.

Style guide

When you are working on the Socket.IO source code, it would be wise to follow our code style guide. Here is a small summary of code styles that we are currently using Socket.IO, following these will make it more likely that your pull request will be accepted:

• When indenting the code use spaces instead of tabs. The indent should be 2 spaces.
• The maximum length of one line of code should be limited to 85 chars.
• All functions should be documented with the JSDoc syntax, with one blank line above and under the comment block.
• Place variables where they make sense, if you define a lot of them, use a comma-first style.
• Line breaks should not be indented.
• Use the dot notation to access properties in an object, except for variables and breaking properties.
• Arrays and objects should be defined using object literals.
• The keys in objects should be defined without quotes, unless it's a keyword.
• If a object definitions spans multiple lines the first key should indented with 4 spaces and the rest of keys should use a comma-first style.
• Use single quotes instead of double quotes.
• Don't extend native prototypes.

There are probably a few more things here and there, so just checkout the style of the document you are working to see how it's styled. Oh No CoffeeScript.

Wiki

Creating new wikis or updating existing wiki's is a great way to contribute to Socket.IO. There is no such thing as too much documentation. Working on wiki's is a lot easier than forking a repository as you can just get started directly by pressing the edit page button at the top of a page.

There enough subjects to be covered:

• Client side api's
• Server side api's
• Best practices
• Tips and tricks
• Configuration options
• Plugins / extending socket.io
• etc.