From ac3e9946829279f98164d449a583d1f0bd716aa0 Mon Sep 17 00:00:00 2001 From: "Sijie.Sun" Date: Sun, 6 Jul 2025 00:08:21 +0800 Subject: [PATCH] contributing.md (#1084) --- CONTRIBUTING.md | 225 +++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING_zh.md | 225 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 450 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING_zh.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..86d9471 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,225 @@ +# Contributing to EasyTier + +[中文版](CONTRIBUTING_zh.md) + +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](#development-environment-setup) + - [Prerequisites](#prerequisites) + - [Installation Steps](#installation-steps) +- [Project Structure](#project-structure) +- [Build Guide](#build-guide) + - [Building Core](#building-core) + - [Building GUI](#building-gui) + - [Building Mobile](#building-mobile) +- [Development Workflow](#development-workflow) +- [Testing Guidelines](#testing-guidelines) +- [Pull Request Guidelines](#pull-request-guidelines) +- [Additional Resources](#additional-resources) + +## Development Environment Setup + +### Prerequisites + +#### Required Tools +- Node.js v21 or higher +- pnpm v9 or higher +- Rust toolchain (version 1.86) +- LLVM and Clang +- Protoc (Protocol Buffers compiler) + +#### Platform-Specific Dependencies + +**Linux (Ubuntu/Debian)** +```bash +# Core build dependencies +sudo apt-get update && sudo apt-get install -y \ + musl-tools \ + libappindicator3-dev \ + 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 \ + 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: + ```bash + git clone https://github.com/EasyTier/EasyTier.git + cd EasyTier + ``` + +2. Install dependencies: + ```bash + # Install Rust toolchain + rustup install 1.86 + rustup default 1.86 + + # 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 + +```bash +# 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 + +```bash +# 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 + +```bash +# 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`: + ```bash + 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 + +```bash +# 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](https://github.com/EasyTier/EasyTier/issues) +- [Project Documentation](https://github.com/EasyTier/EasyTier/wiki) + +## 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! \ No newline at end of file diff --git a/CONTRIBUTING_zh.md b/CONTRIBUTING_zh.md new file mode 100644 index 0000000..588fc0d --- /dev/null +++ b/CONTRIBUTING_zh.md @@ -0,0 +1,225 @@ +# EasyTier 贡献指南 + +[English Version](CONTRIBUTING.md) + +感谢您对 EasyTier 项目的关注！本文档提供了参与项目贡献的指南和说明。 + +## 目录 + +- [开发环境配置](#开发环境配置) + - [前置要求](#前置要求) + - [安装步骤](#安装步骤) +- [项目结构](#项目结构) +- [构建指南](#构建指南) + - [构建核心组件](#构建核心组件) + - [构建桌面应用](#构建桌面应用) + - [构建移动应用](#构建移动应用) +- [开发工作流](#开发工作流) +- [测试指南](#测试指南) +- [Pull Request 规范](#pull-request-规范) +- [其他资源](#其他资源) + +## 开发环境配置 + +### 前置要求 + +#### 必需工具 +- Node.js v21 或更高版本 +- pnpm v9 或更高版本 +- Rust 工具链（版本 1.86） +- LLVM 和 Clang +- Protoc（Protocol Buffers 编译器） + +#### 平台特定依赖 + +**Linux (Ubuntu/Debian)** +```bash +# 核心构建依赖 +sudo apt-get update && sudo apt-get install -y \ + musl-tools \ + libappindicator3-dev \ + llvm \ + clang \ + protobuf-compiler + +# GUI 构建依赖 +sudo apt install -y \ + libwebkit2gtk-4.1-dev \ + build-essential \ + curl \ + wget \ + file \ + libgtk-3-dev \ + librsvg2-dev \ + libxdo-dev \ + libssl-dev \ + patchelf + +# 测试依赖 +sudo apt install -y bridge-utils +``` + +**交叉编译依赖** +- musl-cross 工具链（用于 MIPS 和其他架构） +- 可能需要额外配置（详见 `.github/workflows/` 目录） + +**Android 开发依赖** +- Java 20 +- Android SDK（Build Tools 34.0.0） +- Android NDK（26.0.10792818） + +### 安装步骤 + +1. 克隆仓库： + ```bash + git clone https://github.com/EasyTier/EasyTier.git + cd EasyTier + ``` + +2. 安装依赖： + ```bash + # 安装 Rust 工具链 + rustup install 1.86 + rustup default 1.86 + + # 安装项目依赖 + pnpm -r install + ``` + +## 项目结构 + +``` +easytier/ # 核心功能和库 +easytier-web/ # Web 仪表盘和前端 +easytier-gui/ # 桌面 GUI 应用 +.github/workflows/ # CI/CD 配置文件 +``` + +## 构建指南 + +### 构建核心组件 + +```bash +# 标准构建 +cargo build --release + +# 特定平台构建 +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 +``` + +构建产物位置：`target/[target-triple]/release/` + +### 构建桌面应用 + +```bash +# 1. 构建前端 +pnpm -r build + +# 2. 构建 GUI 应用 +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 +``` + +构建产物位置：`easytier-gui/src-tauri/target/release/bundle/` + +### 构建移动应用 + +```bash +# 1. 安装 Android 目标平台 +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. 构建 Android 应用 +cd easytier-gui +pnpm tauri android build +``` + +构建产物位置：`easytier-gui/src-tauri/gen/android/app/build/outputs/apk/universal/release/` + +### 构建注意事项 + +1. ARM/MIPS 的交叉编译需要额外配置 +2. Windows 构建需要正确的 DLL 文件 +3. 详细构建配置请参考 `.github/workflows/` 目录 + +## 开发工作流 + +1. 从 `develop` 分支创建特性分支： + ```bash + git checkout develop + git checkout -b feature/your-feature-name + ``` + +2. 按照代码规范进行修改 + +3. 编写或更新测试 + +4. 使用规范的提交信息： + ``` + feat: 添加新功能 + fix: 修复问题 + docs: 更新文档 + test: 添加测试 + chore: 更新依赖 + ``` + +5. 提交 Pull Request 到 `develop` 分支 + +## 测试指南 + +### 运行测试 + +```bash +# 配置系统（Linux） +sudo modprobe br_netfilter +sudo sysctl net.bridge.bridge-nf-call-iptables=0 +sudo sysctl net.bridge.bridge-nf-call-ip6tables=0 + +# 运行测试 +cargo test --no-default-features --features=full --verbose +``` + +### 测试要求 + +- 为新功能编写测试 +- 维护现有测试覆盖率 +- 测试应该是独立且可重复的 +- 包含单元测试和集成测试 + +## Pull Request 规范 + +1. 目标分支为 `develop` +2. 确保所有测试通过 +3. 包含清晰的描述和目的 +4. 关联相关的 issues +5. 保持变更的原子性和聚焦性 +6. 及时更新相关文档 + +## 其他资源 + +- [问题追踪](https://github.com/EasyTier/EasyTier/issues) +- [项目文档](https://github.com/EasyTier/EasyTier/wiki) + +## 需要帮助？ + +欢迎： +- 提出问题 +- 参与社区讨论 +- 联系维护者 + +感谢您为 EasyTier 做出贡献！ \ No newline at end of file