mirror of
https://github.com/socketio/socket.io.git
synced 2026-01-08 22:48:20 -05:00
docs: init the contributing guide
Related: https://github.com/socketio/socket.io/issues/4814
This commit is contained in:
Damien Arrachequesne
151
CONTRIBUTING.md
Normal file
151
CONTRIBUTING.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# 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:
|
||||
|
||||
<!-- TOC -->
|
||||
* [Before you start](#before-you-start)
|
||||
* [Guidelines for reporting a bug](#guidelines-for-reporting-a-bug)
|
||||
* [Guidelines for requesting a feature](#guidelines-for-requesting-a-feature)
|
||||
* [Guidelines for creating a pull request](#guidelines-for-creating-a-pull-request)
|
||||
* [Bug fix](#bug-fix)
|
||||
* [New feature](#new-feature)
|
||||
* [Project structure](#project-structure)
|
||||
* [Development setup](#development-setup)
|
||||
* [Commands](#commands)
|
||||
* [Compile with TypeScript](#compile-with-typescript)
|
||||
* [Apply formatting](#apply-formatting)
|
||||
* [Run the tests](#run-the-tests)
|
||||
<!-- TOC -->
|
||||
|
||||
## Before you start
|
||||
|
||||
Our [issues list](https://github.com/socketio/socket.io/issues) is exclusively reserved for bug reports and feature requests. For usage questions, please use the following resources:
|
||||
|
||||
- read the [docs](https://socket.io/docs/v4/)
|
||||
- check the [troubleshooting guide](https://socket.io/docs/v4/troubleshooting-connection-issues/)
|
||||
- look for/ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/socket.io)
|
||||
- create a new [discussion](https://github.com/socketio/socket.io/discussions/new?category=q-a)
|
||||
|
||||
## 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](./SECURITY.md).
|
||||
|
||||
Please make sure that the bug hasn't already been reported in our [issues list](https://github.com/socketio/socket.io/issues?q=label%3Abug+), 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](https://github.com/socketio/socket.io/issues/new/choose) with all the necessary details:
|
||||
|
||||
- package versions
|
||||
- platform (device, browser, operating system)
|
||||
- a minimal reproduction (you can fork [this repository](https://github.com/socketio/socket.io-fiddle))
|
||||
|
||||
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](https://github.com/socketio/socket.io/labels/enhancement).
|
||||
|
||||
After these checks, please [create a new feature request](https://github.com/socketio/socket.io/issues/new/choose) 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](https://github.com/socketio/socket.io/issues), 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](#guidelines-for-reporting-a-bug).
|
||||
- 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](#guidelines-for-requesting-a-feature) 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](https://en.wikipedia.org/wiki/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/component-emitter` | An `EventEmitter` implementation, similar to the one provided by [Node.js](https://nodejs.org/api/events.html) 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](https://nodejs.org) **version 18+**, and [`npm`](https://docs.npmjs.com/about-npm) **version 7+**, as we make use of npm's [workspaces feature](https://docs.npmjs.com/cli/v10/using-npm/workspaces).
|
||||
|
||||
After cloning the repository, please run:
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
```
|
||||
|
||||
to install all dependencies.
|
||||
|
||||
Here is the list of tools that we use:
|
||||
|
||||
- [TypeScript](https://www.typescriptlang.org/) as the development language
|
||||
- [Rollup](https://rollupjs.org/) for production bundling
|
||||
- [Prettier](https://prettier.io/) for code formatting
|
||||
- [Mocha](https://mochajs.org/) for testing
|
||||
- [WebdriverIO](https://webdriver.io/) 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:
|
||||
|
||||
```bash
|
||||
npm run compile -ws --if-present
|
||||
```
|
||||
|
||||
For a specific workspace:
|
||||
|
||||
```bash
|
||||
npm run compile --workspace=socket.io
|
||||
```
|
||||
|
||||
### Apply formatting
|
||||
|
||||
For all workspaces:
|
||||
|
||||
```bash
|
||||
npm run format:fix -ws
|
||||
```
|
||||
|
||||
For a specific workspace:
|
||||
|
||||
```bash
|
||||
npm run format:fix --workspace=socket.io
|
||||
```
|
||||
|
||||
### Run the tests
|
||||
|
||||
For all workspaces:
|
||||
|
||||
```bash
|
||||
npm test -ws
|
||||
```
|
||||
|
||||
For a specific workspace:
|
||||
|
||||
```bash
|
||||
npm test --workspace=socket.io
|
||||
```
|
||||
Reference in New Issue
Block a user