EasyTier/CONTRIBUTING.md

Contributing to EasyTier

中文版

Thank you for your interest in contributing to EasyTier! This document provides guidelines and instructions for contributing to the project.

Table of Contents

• Development Environment Setup
  • Prerequisites
  • Installation Steps
• Project Structure
• Build Guide
  • Building Core
  • Building GUI
  • Building Mobile
• Development Workflow
• Testing Guidelines
• Pull Request Guidelines
• Additional Resources

Development Environment Setup

Prerequisites

Required Tools

• Node.js v21 or higher
• pnpm v9 or higher
• Rust toolchain (version 1.89)
• LLVM and Clang
• Protoc (Protocol Buffers compiler)

Platform-Specific Dependencies

Linux (Ubuntu/Debian)

# Core build dependencies
sudo apt-get update && sudo apt-get install -y \
    musl-tools \
    llvm \
    clang \
    protobuf-compiler

# GUI build dependencies
sudo apt install -y \
    libwebkit2gtk-4.1-dev \
    build-essential \
    curl \
    wget \
    file \
    libgtk-3-dev \
    librsvg2-dev \
    libxdo-dev \
    libssl-dev \
    libappindicator3-dev \
    patchelf

# Testing dependencies
sudo apt install -y bridge-utils

For Cross-Compilation

• musl-cross toolchain (for MIPS and other architectures)
• Additional setup may be required (see .github/workflows/ for details)

For Android Development

• Java 20
• Android SDK (Build Tools 34.0.0)
• Android NDK (26.0.10792818)

Installation Steps

1. Clone the repository:

   git clone https://github.com/EasyTier/EasyTier.git
   cd EasyTier
   

2. Install dependencies:

   # Install Rust toolchain
   rustup install 1.89
   rustup default 1.89
   
   # Install project dependencies
   pnpm -r install
   

Project Structure

easytier/          # Core functionality and libraries
easytier-web/      # Web dashboard and frontend
easytier-gui/      # Desktop GUI application
.github/workflows/ # CI/CD configuration files

Build Guide

Building Core

# Standard build
cargo build --release

# Platform-specific builds
cargo build --release --target x86_64-unknown-linux-musl     # Linux x86_64
cargo build --release --target aarch64-unknown-linux-musl    # Linux ARM64
cargo build --release --target x86_64-apple-darwin           # macOS x86_64
cargo build --release --target aarch64-apple-darwin          # macOS M1/M2
cargo build --release --target x86_64-pc-windows-msvc        # Windows x86_64

Build artifacts: target/[target-triple]/release/

Building GUI

# 1. Build frontend
pnpm -r build

# 2. Build GUI application
cd easytier-gui

# Linux
pnpm tauri build --target x86_64-unknown-linux-gnu

# macOS
pnpm tauri build --target x86_64-apple-darwin      # Intel
pnpm tauri build --target aarch64-apple-darwin     # Apple Silicon

# Windows
pnpm tauri build --target x86_64-pc-windows-msvc   # x64

Build artifacts: easytier-gui/src-tauri/target/release/bundle/

Building Mobile

# 1. Install Android targets
rustup target add aarch64-linux-android
rustup target add armv7-linux-androideabi
rustup target add i686-linux-android
rustup target add x86_64-linux-android

# 2. Build Android application
cd easytier-gui
pnpm tauri android build

Build artifacts: easytier-gui/src-tauri/gen/android/app/build/outputs/apk/universal/release/

Build Notes

1. Cross-compilation for ARM/MIPS requires additional setup
2. Windows builds need correct DLL files
3. Check .github/workflows/ for detailed build configurations

Development Workflow

1. Create a feature branch from develop:

   git checkout develop
   git checkout -b feature/your-feature-name
   

2. Make your changes following our coding standards

3. Write or update tests as needed

4. Use conventional commit messages:

   feat: add new feature
   fix: resolve bug
   docs: update documentation
   test: add tests
   chore: update dependencies
   

5. Submit a pull request to develop

Testing Guidelines

Running Tests

# Configure system (Linux)
sudo modprobe br_netfilter
sudo sysctl net.bridge.bridge-nf-call-iptables=0
sudo sysctl net.bridge.bridge-nf-call-ip6tables=0

# Run tests
cargo test --no-default-features --features=full --verbose

Test Requirements

• Write tests for new features
• Maintain existing test coverage
• Tests should be isolated and repeatable
• Include both unit and integration tests

Pull Request Guidelines

1. Target the develop branch
2. Ensure all tests pass
3. Include clear description and purpose
4. Reference related issues
5. Keep changes focused and atomic
6. Update documentation as needed

Additional Resources

• Issue Tracker
• Project Documentation

Questions or Need Help?

Feel free to:

• Open an issue for questions
• Join our community discussions
• Reach out to maintainers

Thank you for contributing to EasyTier!