Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
158 lines (115 loc) · 5.22 KB

CONTRIBUTING.md

File metadata and controls

158 lines (115 loc) · 5.22 KB
Raw

Contributing to MyRank

感謝你對 MyRank 的興趣！以下是貢獻指南。

開發環境設置

需求

  • JDK 21（推薦 Eclipse Temurin）
  • Gradle 9.5+（project wrapper included）
  • Git

編譯

.\gradlew compileJava          # 編譯所有版本
.\gradlew :1.20.4:build       # 編譯特定版本
.\gradlew buildAndGather       # 構建全部版本 jar

項目結構

src/main/java/me/qmkcat/myrank/
├── MyRankMod.java              # Entry point & logging
├── MyRankManager.java           # Main coordinator & state management (simplifying)
├── MyRankCommand.java           # Command dispatcher
├── MyRankRanking.java           # Ranking calculation & score collection
├── MyRankDisplay.java           # Sidebar rendering & objective management
├── MyRankTranslator.java        # Server-side translation
├── MyRankTexts.java             # Text building helpers
├── MyRankPermissions.java        # Permission node resolution
└── mixins/                      # Server-side only mixins

src/main/resources/assets/myrank/lang/
├── en_us.yml                    # English (fallback)
├── zh_tw.yml                    # Traditional Chinese
└── zh_cn.yml                    # Simplified Chinese

代碼風格

  • 無自動格式化工具；遵循 Google Java Format（2-space indent）
  • 默認不寫註解，只在 WHY 非明顯時添加單行註解
  • 版本差異用 //#if MC >= 12003 預處理指令標記
  • 記住：never break preprocessor directives（GJF 會偷偷破壞它們）

添加新版本支援

  1. 在 settings.json 的 versions 添加版本（如 1.22.0）
  2. 複製 versions/<closest>/gradle.properties 至 versions/1.22.0/，調整 Minecraft 版本
  3. 在 build.gradle preprocess 區塊添加 createNode 並用 link 連接
  4. 在代碼中用 //#if MC >= 12200 標記版本差異

參考資源：

多語言

語言鍵在 src/main/resources/assets/myrank/lang/ 的 .yml 檔案。使用 yamlang 格式，會在編譯時驗證：

.\gradlew :1.17.1:processResources  # 驗證語言檔

加新語言只需新增一個檔案（如 ja_jp.yml）——缺少的鍵自動 fallback 到 en_us。

提交指南

  • 清晰簡潔的提交訊息（英文），解釋 WHY 不是 WHAT
  • 不要添加未相關的變更；一個 PR 一個問題
  • 編譯必須通過：.\gradlew compileJava
  • 測試時用 run/config/myrank.json 存放測試數據

Pull Request

  1. Fork 並創建特性分支
  2. 提交清晰的提交訊息
  3. 測試所支援的版本（至少 1.17.1 和 1.20.4）
  4. 提交 PR 與詳細描述

Contributing (English)

Thank you for your interest in MyRank! Here's the contribution guide.

Development Setup

Requirements

  • JDK 21 (Eclipse Temurin recommended)
  • Gradle 9.5+ (project wrapper included)
  • Git

Building

.\gradlew compileJava          # Compile all versions
.\gradlew :1.20.4:build       # Compile specific version
.\gradlew buildAndGather       # Build all version jars

Project Structure

src/main/java/me/qmkcat/myrank/
├── MyRankMod.java              # Entry point & logging
├── MyRankManager.java           # Main coordinator & state management
├── MyRankCommand.java           # Command dispatcher
├── MyRankRanking.java           # Ranking calculation & score collection
├── MyRankDisplay.java           # Sidebar rendering & objective management
├── MyRankTranslator.java        # Server-side translation
├── MyRankTexts.java             # Text building helpers
├── MyRankPermissions.java        # Permission node resolution
└── mixins/                      # Server-side only mixins

Code Style

  • No automatic formatting; follow Google Java Format (2-space indent)
  • No comments by default; add single-line comments only when WHY is non-obvious
  • Version differences marked with //#if MC >= 12003 preprocessor directives
  • Remember: never break preprocessor directives (formatters silently corrupt them)

Adding Version Support

  1. Add version to versions in settings.json (e.g. 1.22.0)
  2. Copy versions/<closest>/gradle.properties to versions/1.22.0/, adjust MC version
  3. Add createNode in build.gradle preprocess block and link it
  4. Mark version differences in code with //#if MC >= 12200

Resources:

Multi-language

Language keys in .yml files under src/main/resources/assets/myrank/lang/. Uses yamlang format, validated at compile time:

.\gradlew :1.17.1:processResources  # Validate language files

Add a new language by creating a file (e.g. ja_jp.yml) — missing keys auto-fallback to en_us.

Commit Guidelines

  • Clear, concise commit messages (English), explain WHY not WHAT
  • Don't mix unrelated changes; one PR per issue
  • Compilation must pass: .\gradlew compileJava
  • Test config stored in run/config/myrank.json

Pull Requests

  1. Fork and create a feature branch
  2. Write clear commit messages
  3. Test supported versions (at least 1.17.1 and 1.20.4)
  4. Submit PR with detailed description