# Contributing to Huly Virtual Network First off, thank you for considering contributing to Huly Virtual Network! It's people like you that make this project such a great tool. ## Table of Contents - [Code of Conduct](#code-of-conduct) - [How Can I Contribute?](#how-can-i-contribute) - [Development Setup](#development-setup) - [Pull Request Process](#pull-request-process) - [Coding Standards](#coding-standards) - [Testing Guidelines](#testing-guidelines) - [Commit Message Guidelines](#commit-message-guidelines) ## Code of Conduct This project and everyone participating in it is governed by our commitment to providing a welcoming and inspiring community for all. Please be respectful and constructive in your interactions. ## How Can I Contribute? ### Reporting Bugs Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible: - **Use a clear and descriptive title** - **Describe the exact steps to reproduce the problem** - **Provide specific examples** (code snippets, test cases) - **Describe the behavior you observed** and what you expected - **Include logs and error messages** - **Specify your environment** (Node.js version, OS, etc.) ### Suggesting Enhancements Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion: - **Use a clear and descriptive title** - **Provide a detailed description** of the suggested enhancement - **Explain why this enhancement would be useful** - **List any alternatives you've considered** ### Pull Requests We actively welcome your pull requests: 1. Fork the repo and create your branch from `main` 2. If you've added code that should be tested, add tests 3. If you've changed APIs, update the documentation 4. Ensure the test suite passes 5. Make sure your code follows the existing style 6. Issue your pull request! ## Development Setup ### Prerequisites - **Node.js**: 22.0.0 or higher - **PNPM**: 10.15.1 or higher (installed automatically via Rush) - **ZeroMQ**: Native dependencies (libzmq) ### Initial Setup ```bash # Clone your fork git clone https://github.com/YOUR_USERNAME/huly.net.git cd huly.net # Install dependencies node common/scripts/install-run-rush.js install # Build all packages node common/scripts/install-run-rush.js build ``` ### Project Structure ``` huly.net/ ├── packages/ │ ├── core/ # Core network implementation │ ├── backrpc/ # ZeroMQ RPC layer │ ├── client/ # Client libraries │ └── server/ # Server implementation ├── pods/ │ └── network-pod/ # Docker deployment ├── tests/ # Integration tests ├── examples/ # Example code └── docs/ # Documentation ``` ### Development Workflow ```bash # Run tests node common/scripts/install-run-rush.js test # Run tests for a specific package cd packages/core && npm test # Build with watch mode (during development) node common/scripts/install-run-rush.js build:watch # Format code node common/scripts/install-run-rush.js format # Validate TypeScript node common/scripts/install-run-rush.js validate ``` ## Pull Request Process 1. **Update Documentation**: Ensure any new features or changes are documented 2. **Add Tests**: Include tests for new functionality 3. **Update CHANGELOG**: Add your changes to the appropriate package CHANGELOG.md 4. **Pass CI**: Ensure all tests pass in CI 5. **Request Review**: Tag relevant maintainers for review 6. **Sign Commits**: Use `git commit -s` to sign off on your commits ### PR Title Format Use descriptive PR titles that follow this format: ``` [Package] Brief description of changes Examples: [core] Add support for custom container timeouts [client] Fix reconnection logic for dropped connections [docs] Update production deployment guide ``` ## Coding Standards ### TypeScript Style - **Use TypeScript strict mode**: All code must pass strict type checking - **Prefer interfaces over types** for object shapes - **Use async/await** over raw Promises - **Document public APIs** with JSDoc comments - **Use descriptive variable names**: No single-letter variables except in loops ### Code Organization ```typescript // 1. Imports (grouped: external, internal, types) import { EventEmitter } from 'events' import { NetworkImpl } from '../network' import type { Container, ContainerUuid } from '../types' // 2. Types and interfaces interface MyOptions { timeout: number } // 3. Class implementation export class MyClass { // Private fields first private readonly config: MyOptions // Constructor constructor(options: MyOptions) { this.config = options } // Public methods async doSomething(): Promise { // Implementation } // Private methods private helper(): void { // Implementation } } ``` ### Error Handling - **Always handle errors explicitly**: No silent failures - **Use typed errors**: Create custom error classes when needed - **Provide context**: Include relevant information in error messages ```typescript // Good try { await operation() } catch (error: any) { throw new Error(`Failed to perform operation: ${error.message}`) } // Bad try { await operation() } catch (error) { // Silent failure } ``` ## Testing Guidelines ### Test Structure ```typescript describe('ComponentName', () => { describe('methodName', () => { it('should behave correctly under normal conditions', async () => { // Arrange const component = new ComponentName() // Act const result = await component.methodName() // Assert expect(result).toBe(expected) }) it('should handle error conditions', async () => { // Test error cases }) }) }) ``` ### Test Coverage - **Aim for 80%+ coverage**: All new code should have tests - **Test edge cases**: Don't just test the happy path - **Test error conditions**: Verify error handling works correctly - **Integration tests**: Add tests that verify component interaction ### Running Tests ```bash # Run all tests node common/scripts/install-run-rush.js test # Run tests for a specific package cd packages/core npm test # Run tests in watch mode npm test -- --watch # Generate coverage report npm test -- --coverage ``` ## Commit Message Guidelines We follow conventional commits for clear git history: ### Format ``` ():