Skip to content

Latest commit

 

History

History
324 lines (229 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

324 lines (229 loc) · 10.5 KB

Contributing to NodePass

Thank you for your interest in contributing to NodePass! We welcome all kinds of contributions, from bug reports and feature requests to code improvements and documentation updates.

Table of Contents

Code of Conduct

Please read and follow our Code of Conduct. We are committed to providing a welcoming and inclusive environment for all contributors.

Getting Started

Prerequisites

  • Go 1.25+ (as specified in go.mod)
  • Git for version control
  • Docker (optional, for container-based development and testing)
  • Basic knowledge of TCP/UDP networking concepts
  • Familiarity with TLS/SSL concepts for security features

Understanding the Architecture

NodePass is built on a three-tier architecture:

  • Server Mode: Accepts incoming tunnel connections with configurable security
  • Client Mode: Establishes outbound connections to tunnel servers
  • Master Mode: Provides RESTful API for dynamic instance management

Key components:

  • /cmd/nodepass/: Main application entry point and core dispatch logic
  • /internal/: Core implementation packages (server, client, master, common utilities)
  • /docs/: Comprehensive documentation in English and Chinese
  • External dependencies: NodePassProject ecosystem libraries for certificates, connections, logging, and pooling

Development Setup

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/nodepass.git
cd nodepass

# Add the upstream repository
git remote add upstream https://github.com/NodePassProject/nodepass.git

2. Install Dependencies

# Download and install dependencies
go mod download

# Verify dependencies
go mod verify

3. Build and Test

# Build the application
go build -o nodepass ./cmd/nodepass

# Test the build
./nodepass "server://localhost:10101/127.0.0.1:8080?log=debug&tls=0"

4. Development with Docker (Optional)

# Build development container
docker build --build-arg VERSION=dev -t nodepass:dev .

# Run in container
docker run --rm -p 10101:10101 nodepass:dev "server://:10101/127.0.0.1:8080?log=debug&tls=0"

Contributing Guidelines

Types of Contributions

  • Bug Reports: Help us identify and fix issues
  • Feature Requests: Suggest new features or improvements
  • Documentation: Improve existing docs or add new ones
  • Code Contributions: Bug fixes, feature implementations, refactoring
  • Translations: Help translate documentation to other languages
  • Testing: Add test cases and improve test coverage

Reporting Issues

When reporting bugs or requesting features, please:

  1. Search existing issues to avoid duplicates
  2. Use our issue templates when available
  3. Provide detailed information:
    • NodePass version and build information
    • Operating system and architecture
    • Network configuration details
    • Complete command-line arguments used
    • Expected vs. actual behavior
    • Relevant log output (use log=debug for detailed logs)
    • Steps to reproduce the issue

Feature Requests

For new features:

  1. Check the roadmap and existing feature requests
  2. Describe the use case clearly
  3. Explain the expected behavior
  4. Consider backwards compatibility
  5. Discuss implementation approach if you plan to contribute code

Code Style and Standards

Go Code Style

We follow standard Go conventions with project-specific guidelines:

  • Write idiomatic Go code following Effective Go
  • Use gofmt for consistent formatting and go vet to catch common errors
  • Follow the single responsibility principle and prefer composition over inheritance
  • Use descriptive variable and function names with proper Go naming conventions
  • Include both Chinese and English comments for public APIs (maintaining project tradition)
  • Implement proper error handling with context wrapping
  • Use the project's logging framework consistently with appropriate log levels
  • Protect shared state with mutexes and use channels for goroutine coordination
  • Always handle goroutine cleanup with proper defer and recover patterns

Configuration and CLI

  • Use URL-based configuration syntax: scheme://[password@]host:port/target?param=value
  • Support environment variables for sensitive configuration
  • Provide sensible defaults for all optional parameters
  • Validate configuration early in the application lifecycle

Performance Considerations

  • Minimize allocations in hot paths
  • Use connection pooling for frequent connections
  • Implement graceful degradation under load
  • Profile memory and CPU usage for critical paths
  • Use buffered I/O where appropriate

Testing

Testing Strategy

Currently, the project focuses on integration testing through real-world usage scenarios. We welcome contributions to improve test coverage:

Manual Testing

  1. Basic Functionality: Test server, client, and master modes with debug logging
  2. TLS Modes: Verify all three TLS security levels (0, 1, 2)
  3. Protocol Support: Test TCP tunneling and UDP forwarding with various applications

Future Testing Goals

We encourage contributions in these areas:

  • Unit Tests for individual functions and methods
  • Integration Tests for component interactions
  • Benchmark Tests for performance regression detection
  • Fuzzing Tests for security and robustness
  • End-to-End Tests for complete workflow validation

Testing Guidelines

When adding tests:

  • Use Go's standard testing package with *_test.go naming convention
  • Write table-driven tests where applicable
  • Include both positive and negative test cases
  • Test error conditions and edge cases
  • Use meaningful test names that describe the scenario

Documentation

Documentation Standards

  • Write in clear, simple English
  • Include practical examples for all features
  • Maintain both English and Chinese versions when possible
  • Use consistent formatting and structure
  • Test all code examples to ensure they work

Documentation Structure

  • README.md: Project overview and quick start
  • docs/en/: English documentation
  • docs/zh/: Chinese documentation
  • Inline code comments for complex logic
  • API documentation for master mode endpoints

Contributing to Documentation

  1. Update both language versions when possible
  2. Test all examples before submitting
  3. Use proper Markdown formatting
  4. Include relevant screenshots for UI components
  5. Cross-reference related documentation

Submitting Changes

Pull Request Process

  1. Create a feature branch from the latest main:

    git checkout main
git pull upstream main
git checkout -b feature/your-feature-name

  2. Make your changes following the guidelines above

  3. Test your changes thoroughly by building the application and running real scenarios

  4. Commit your changes with descriptive messages using Conventional Commits format:

    • feat: New feature
    • fix: Bug fix
    • docs: Documentation changes
    • refactor: Code refactoring
    • perf: Performance improvements
    • test: Adding or updating tests

  5. Push to your fork and create a pull request

Commit Message Guidelines

Use Conventional Commits format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Examples:

  • feat(server): add support for IPv6 addresses
  • fix(client): resolve connection timeout issues in high-latency networks
  • docs: update installation guide with Docker instructions
  • refactor(common): simplify address parsing logic

Pull Request Guidelines

Before submitting:

  • Code follows the project style guidelines
  • All tests pass (or explain why they should be skipped)
  • Documentation is updated if needed
  • Commit messages follow the conventional format
  • No merge conflicts with the main branch

In your pull request:

  • Provide a clear description of changes
  • Reference any related issues
  • Include testing instructions
  • Add screenshots for UI changes
  • List any breaking changes

Review Process

Pull requests go through the following stages:

  1. Automated checks run on all pull requests
  2. Code review by project maintainers
  3. Testing in various environments
  4. Documentation review for user-facing changes
  5. Final approval and merge

Community and Support

Communication Channels

Getting Help

If you need help:

  1. Check the documentation in the docs/ directory
  2. Search existing issues for similar problems
  3. Ask in our community channels for general questions
  4. Create a GitHub issue for bugs or feature requests

Recognition

We appreciate all contributions! Contributors will be:

  • Listed in our contributors section
  • Mentioned in release notes for significant contributions
  • Invited to become maintainers for consistent, high-quality contributions

Maintainer Responsibilities

Current maintainers handle:

  • Code review and pull request management
  • Release planning and version management
  • Community management and support
  • Security issue handling
  • Roadmap planning and prioritization

Thank you for contributing to NodePass! Your contributions help make universal TCP/UDP tunneling more accessible and reliable for everyone.

For questions about contributing, please reach out through our community channels or create a GitHub issue.