CONTRIBUTING.md

Socket.IO Contributing Guide (Go Version)

Thank you for your interest in contributing to the Go implementation of Socket.IO at github.com/zishang520/socket.io!

To ensure a smooth collaboration process, please read the following guidelines before you get started.

• Before You Start
• Reporting Bugs
• Requesting Features
• Creating Pull Requests
  • Bug Fixes
  • New Features
• Project Structure
• Development Setup
• Useful Commands
  • Code Formatting
  • Running Tests

Before You Start

• Our issues list is reserved for bug reports and feature requests.
• For general usage questions, please refer to:
  • the documentation
  • or open a discussion

Reporting Bugs

• First, check if your issue already exists in the bug label.
• If it has been reported but closed and still persists, open a new issue instead of commenting on the old one.
• For security-related bugs, do not open a public issue. Refer to our security policy.

When creating a bug report:

• Include Go module versions
• Specify the platform (OS, architecture)
• Provide a minimal reproducible example (see examples/docs)

Requesting Features

• Check for similar feature requests in the enhancement list.
• If none exist, submit a new feature request.

Include:

• The problem you're trying to solve
• Your proposed solution
• Alternatives or workarounds considered

Creating Pull Requests

We welcome PRs for bug fixes, new features, and improvements.

Bug Fixes

• Reference the related issue (if any)
• Add test cases to prevent future regressions
• Ensure all existing tests pass

New Features

• Please open a feature request first to discuss it
• Include tests and documentation
• Make sure all tests pass before submitting

Project Structure

This is a Go monorepo. Each submodule is organized as an independent Go module:

Go Module	Description
github.com/zishang520/socket.io/v3	Root module defining shared types, interfaces, and entry points.
github.com/zishang520/socket.io/servers/engine/v3	Engine.IO server: manages low-level communication via transports.
github.com/zishang520/socket.io/clients/engine/v3	Engine.IO client: low-level transport connection to server.
github.com/zishang520/socket.io/parsers/engine/v3	Engine.IO packet parser: encodes/decodes transport-level messages.
github.com/zishang520/socket.io/servers/socket/v3	Socket.IO server: built on Engine.IO server for real-time, bidirectional communication.
github.com/zishang520/socket.io/clients/socket/v3	Socket.IO client: built on Engine.IO client with rooms, namespaces, etc.
github.com/zishang520/socket.io/parsers/socket/v3	Socket.IO packet parser: handles event-based message encoding/decoding.
github.com/zishang520/socket.io/adapters/adapter/v3	Adapter interface: plug-and-play broadcast layer for multi-node communication.
github.com/zishang520/socket.io/adapters/redis/v3	Redis-based adapter: enables pub/sub message broadcasting via Redis.
github.com/zishang520/socket.io/adapters/valkey/v3	Valkey-based adapter: enables pub/sub message broadcasting via Valkey.
github.com/zishang520/socket.io/adapters/postgres/v3	PostgreSQL-based adapter: enables pub/sub message broadcasting via PostgreSQL LISTEN/NOTIFY.
github.com/zishang520/socket.io/adapters/mongo/v3	MongoDB-based adapter: enables pub/sub message broadcasting via MongoDB change streams.
github.com/zishang520/socket.io/adapters/unix/v3	Unix Domain Socket-based adapter: enables low-latency message broadcasting across processes on the same machine.

Development Setup

• Install Go version 1.26.0+
• Clone the repository and use Go Workspaces (go work) to link submodules if needed

Useful Commands

Code Formatting

Format all workspaces:

make fmt

Format a specific workspace:

Windows:

make fmt servers/socket

Unix:

make fmt MODULE=servers/socket

Running Tests

Run all tests:

make test

Test a specific workspace:

Windows:

make test servers/socket

Unix:

make test MODULE=servers/socket

---

Feel free to open an issue or discussion if you have any questions. Happy hacking! ✨