Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
362 lines (260 loc) · 8.46 KB

CONTRIBUTING.md

File metadata and controls

362 lines (260 loc) · 8.46 KB

贡献指南 | Contributing Guide

English | 中文

中文

感谢你对 EasyPostman 的关注！我们欢迎任何形式的贡献。

🚀 开始之前

在提交贡献之前，请确保：

  1. 已阅读 README 了解项目
  2. 已搜索 Issues 确认问题未被报告
  3. 已阅读本贡献指南

📋 贡献方式

1. 报告 Bug

如果你发现了 Bug，请：

  1. 在 Issues 中搜索是否已有相同问题
  2. 如果没有，创建新的 Issue，选择 "🐛 Bug 报告" 模板
  3. 填写完整的信息，包括：
    • 复现步骤
    • 期望行为和实际行为
    • 环境信息（操作系统、版本号等）
    • 相关日志和截图

2. 功能建议

如果你有新功能的想法：

  1. 先在 Discussions 中讨论
  2. 如果获得认可，创建 Issue，选择 "✨ 功能请求" 模板
  3. 详细描述：
    • 使用场景
    • 期望的解决方案
    • 备选方案
    • 界面设计（如果涉及 UI）

3. 提交代码

我们非常欢迎代码贡献！

环境准备
# 1. Fork 项目到你的 GitHub 账号

# 2. 克隆你的 Fork
git clone https://github.com/YOUR_USERNAME/easy-postman.git
cd easy-postman

# 3. 添加上游仓库
git remote add upstream https://github.com/lakernote/easy-postman.git

# 4. 安装依赖
# 确保已安装 Java 17+
mvn clean install
开发流程
# 1. 同步最新代码
git checkout main
git pull upstream main

# 2. 创建功能分支
git checkout -b feature/your-feature-name
# 或修复分支
git checkout -b fix/your-bug-fix

# 3. 进行开发
# ... 编码 ...

# 4. 编译测试
mvn clean package
mvn test

# 5. 提交代码
git add .
git commit -m "feat: 添加新功能描述"
# 或
git commit -m "fix: 修复某个问题"

# 6. 推送到你的 Fork
git push origin feature/your-feature-name

# 7. 创建 Pull Request
# 在 GitHub 上创建 PR，从你的分支到 upstream/main
代码规范
  • 编码风格：遵循 Java 编码规范
  • 提交信息：使用语义化提交信息
    • feat: 新功能
    • fix: Bug 修复
    • docs: 文档更新
    • style: 代码格式调整
    • refactor: 代码重构
    • perf: 性能优化
    • test: 测试相关
    • chore: 构建/工具相关
  • 注释：为复杂逻辑添加清晰的注释
  • 测试：为新功能添加测试用例
Pull Request 检查清单

在提交 PR 前，请确保：

  • 代码可以成功编译（mvn clean package）
  • 所有测试通过（mvn test）
  • 代码遵循项目的编码规范
  • 添加了必要的注释
  • 更新了相关文档（如果需要）
  • PR 描述清晰，说明了改动内容和原因
  • 关联了相关的 Issue（如果有）

4. 改进文档

文档同样重要！你可以：

  • 修正错别字或不准确的描述
  • 补充使用示例
  • 翻译文档
  • 添加常见问题解答

🎯 开发建议

项目结构

src/main/java/com/laker/
├── postman/           # 主应用
│   ├── ui/           # UI 组件
│   ├── service/      # 业务逻辑
│   ├── model/        # 数据模型
│   ├── utils/        # 工具类
│   └── network/      # 网络请求
└── ...

技术栈

  • UI 框架: JavaFX / Swing + FlatLaf
  • HTTP 客户端: OkHttp
  • JSON 处理: Jackson / Gson
  • Git 集成: JGit
  • 脚本引擎: GraalVM Polyglot

调试技巧

# 开发模式运行
mvn clean compile exec:java -Dexec.mainClass="com.laker.postman.App"

# 启用调试日志
# 修改 src/main/resources/logback.xml 中的日志级别

🤝 行为准则

  • 尊重他人，友好交流
  • 接受建设性的批评
  • 专注于对项目最有利的事情
  • 对新手保持耐心和包容

📞 联系方式

🙏 感谢

感谢所有为 EasyPostman 做出贡献的开发者！

English

Thank you for your interest in EasyPostman! We welcome all forms of contributions.

🚀 Before You Start

Before contributing, please ensure:

  1. You've read the README to understand the project
  2. You've searched Issues to confirm the issue hasn't been reported
  3. You've read this contributing guide

📋 Ways to Contribute

1. Report Bugs

If you find a bug:

  1. Search Issues for existing reports
  2. If none exist, create a new Issue using the "🐛 Bug Report" template
  3. Fill in complete information including:
    • Reproduction steps
    • Expected vs actual behavior
    • Environment info (OS, version, etc.)
    • Relevant logs and screenshots

2. Suggest Features

If you have a feature idea:

  1. Discuss it in Discussions first
  2. If approved, create an Issue using the "✨ Feature Request" template
  3. Describe in detail:
    • Use cases
    • Desired solution
    • Alternative solutions
    • UI mockups (if applicable)

3. Submit Code

We welcome code contributions!

Setup Environment
# 1. Fork the project to your GitHub account

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/easy-postman.git
cd easy-postman

# 3. Add upstream remote
git remote add upstream https://github.com/lakernote/easy-postman.git

# 4. Install dependencies
# Ensure Java 17+ is installed
mvn clean install
Development Workflow
# 1. Sync latest code
git checkout main
git pull upstream main

# 2. Create feature branch
git checkout -b feature/your-feature-name
# or fix branch
git checkout -b fix/your-bug-fix

# 3. Develop
# ... code ...

# 4. Build and test
mvn clean package
mvn test

# 5. Commit changes
git add .
git commit -m "feat: add new feature description"
# or
git commit -m "fix: fix some issue"

# 6. Push to your fork
git push origin feature/your-feature-name

# 7. Create Pull Request
# Create PR on GitHub from your branch to upstream/main
Code Standards
  • Code Style: Follow Java coding standards
  • Commit Messages: Use semantic commit messages
    • feat: New feature
    • fix: Bug fix
    • docs: Documentation update
    • style: Code formatting
    • refactor: Code refactoring
    • perf: Performance improvement
    • test: Test related
    • chore: Build/tools related
  • Comments: Add clear comments for complex logic
  • Tests: Add test cases for new features
Pull Request Checklist

Before submitting a PR, ensure:

  • Code compiles successfully (mvn clean package)
  • All tests pass (mvn test)
  • Code follows project coding standards
  • Added necessary comments
  • Updated relevant documentation (if needed)
  • PR description is clear, explaining changes and reasons
  • Linked related Issues (if any)

4. Improve Documentation

Documentation is equally important! You can:

  • Fix typos or inaccurate descriptions
  • Add usage examples
  • Translate documentation
  • Add FAQ entries

🎯 Development Tips

Project Structure

src/main/java/com/laker/
├── postman/           # Main application
│   ├── ui/           # UI components
│   ├── service/      # Business logic
│   ├── model/        # Data models
│   ├── utils/        # Utilities
│   └── network/      # Network requests
└── ...

Tech Stack

  • UI Framework: JavaFX / Swing + FlatLaf
  • HTTP Client: OkHttp
  • JSON Processing: Jackson / Gson
  • Git Integration: JGit
  • Script Engine: GraalVM Polyglot

Debug Tips

# Run in development mode
mvn clean compile exec:java -Dexec.mainClass="com.laker.postman.App"

# Enable debug logging
# Modify log level in src/main/resources/logback.xml

🤝 Code of Conduct

  • Respect others, communicate kindly
  • Accept constructive criticism
  • Focus on what's best for the project
  • Be patient and inclusive with newcomers

📞 Contact

🙏 Acknowledgments

Thanks to all developers who have contributed to EasyPostman!