CONTRIBUTING.md

Socket.IO Contributing Guide

Thanks a lot for your interest in contributing to Socket.IO!

Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

• Before you start
• Guidelines for reporting a bug
• Guidelines for requesting a feature
• Guidelines for creating a pull request
  • Bug fix
  • New feature
• Project structure
• Development setup
• Commands
  • Compile with TypeScript
  • Apply formatting
  • Run the tests

Before you start

Our issues list is exclusively reserved for bug reports and feature requests. For usage questions, please use the following resources:

• read the docs
• check the troubleshooting guide
• look for/ask questions on Stack Overflow
• create a new discussion

Guidelines for reporting a bug

If you think that you have found a security vulnerability in our project, please do not create an issue in this GitHub repository, but rather refer to our security policy.

Please make sure that the bug hasn't already been reported in our issues list, as it may already have been fixed in a recent version. However, if the bug was reported in an old, closed issue but persists, you should open a new issue instead of commenting on the old issue.

After these checks, please create a new bug report with all the necessary details:

• package versions
• platform (device, browser, operating system)
• a minimal reproduction (you can fork this repository)

Without a clear way to reproduce the bug, we unfortunately won't be able to help you.

Guidelines for requesting a feature

Please make sure that the feature hasn't already been requested in our issues list.

After these checks, please create a new feature request with all the necessary details:

• what the problem is
• what you want to happen
• any alternative solutions or features you have considered

Guidelines for creating a pull request

Bug fix

• if you fix a bug which is described in our issues list, please add a reference to it in the description of your pull request. Otherwise, please provide all necessary details to reproduce the bug, as described above.
• add one or more test cases, in order to avoid any regression in the future
• make sure existing tests still pass

New feature

• we strongly suggest that you first open a feature request and have it approved before working on it. In that case, please add a reference to it in the description of your pull request.
• add one or more test cases, in order to avoid any regression in the future
• make sure existing tests still pass

Project structure

This repository is a monorepo which contains the source of the following packages:

Package	Description
engine.io	The server-side implementation of the low-level communication layer.
engine.io-client	The client-side implementation of the low-level communication layer.
engine.io-parser	The parser responsible for encoding and decoding Engine.IO packets, used by both the engine.io and engine.io-client packages.
socket.io	The server-side implementation of the bidirectional channel, built on top on the engine.io package.
socket.io-adapter	An extensible component responsible for broadcasting a packet to all connected clients, used by the socket.io package.
socket.io-client	The client-side implementation of the bidirectional channel, built on top on the engine.io-client package.
@socket.io/cluster-engine	A cluster-friendly engine to share load between multiple Node.js processes (without sticky sessions)
@socket.io/component-emitter	An EventEmitter implementation, similar to the one provided by Node.js but for all platforms.
socket.io-parser	The parser responsible for encoding and decoding Socket.IO packets, used by both the socket.io and socket.io-client packages.

Development setup

You will need Node.js version 18+, and npm version 7+, as we make use of npm's workspaces feature.

After cloning the repository, please run:

npm ci

to install all dependencies.

Here is the list of tools that we use:

• TypeScript as the development language
• Rollup for production bundling
• Prettier for code formatting
• Mocha for testing
• WebdriverIO for browser and mobile testing

Commands

Each npm workspace corresponds to a package. You can run the command:

• on all workspaces with the --workspace command-line argument (abbreviated -ws)
• on a specific workspace with the --workspace=<some-workspace> command-line argument

Compile with TypeScript

For all workspaces:

npm run compile -ws --if-present

For a specific workspace:

npm run compile --workspace=socket.io

Apply formatting

For all workspaces:

npm run format:fix -ws

For a specific workspace:

npm run format:fix --workspace=socket.io

Run the tests

For all workspaces:

npm test -ws

For a specific workspace:

npm test --workspace=socket.io

Generate the changelog

Install the conventional-changelog-cli package:

npm i -g conventional-changelog-cli

Then run:

cd packages/engine.io-client
conventional-changelog -p angular --tag-prefix "engine.io-client@" --commit-path .