贡献指南
NextDoc4j 致力于为 Java 开发者提供强大而易用的现代化 API 调试工作台。作为开源社区驱动的项目，我们诚挚欢迎大家参与 Issue 排查、新特性开发、文档编写与测试验证。
开源协作CLA 协议Spotless 自动格式化Angular Commit 规范
代码托管平台
Gitee 是项目主仓库，GitHub 与 GitCode 提供同步入口，您可以从下方平台查看源码或参与协作：
贡献必读
如果您是开源贡献新手，建议先阅读以下权威指引，了解参与开源项目的流程与最佳协作姿势：
| 参考文档 | 核心简介 | 访问地址 |
|---|---|---|
| 《开源项目礼节》 | 涵盖开源协作中的最佳沟通实践，帮助您在社区中保持高效友善沟通 | MDN 社区指南 |
| 《如何为开源做贡献》 | 专为初学者准备的开源贡献指南，从 Git 基础到 PR 流程一应俱全 | Open Source Guide |
分支管理模型
NextDoc4j 项目采用清晰的主干/开发分支策略，提交 PR 前请确认目标分支：
| 分支名称 | 定位说明 | PR 接收策略 |
|---|---|---|
master | 稳定发布分支，对应 Maven 中央仓库正式发版 | ❌ 仅限维护者发版合并，不直接接收开发 PR |
dev | 日常开发主干分支，包含最新特性与测试代码 | ✅ 接收所有新功能特性（Feature）与 Bug 修复 PR |
贡献代码八步流程
1Fork 官方仓库
在 Gitee 页面点击右上角 Fork 按钮，将 nextdoc4j/nextdoc4j 派生至您的个人账号空间。
2克隆到本地开发环境
执行 git clone https://gitee.com/your-username/nextdoc4j.git 将代码拉取至本地环境。
3基于 dev 分支创建特性分支
从最新的 dev 分支拉取新分支：git checkout -b feat/your-feature-name，请勿直接在 master 上开发。
4本地编码与规范格式化
编写业务逻辑并补齐单元测试。提交前在项目根目录运行 mvn compile 进行 Spotless 自动代码格式化与合规校验。
5推送并提交 Pull Request (PR)
推送到个人远程仓库后在 Gitee 发起 PR，目标分支选择官方 dev，按模板详细说明变更背景与测试结果。
6签署 CLA 贡献者协议
机器人会引导签署 CLA 协议。请确保 Commit 中的作者邮箱与代码托管平台账号绑定的主邮箱一致。
7等待核心团队 Review
核心团队会及时审阅代码并给出修改建议，讨论通过且自动化 CI 全绿后予以合并。
8清理分支并同步最新代码
PR 合并后在本地删除临时分支，并从官方 upstream 同步最新提交，准备开启下一次贡献。
PR 终端操作速记流
# 1. 克隆并进入目录
git clone https://gitee.com/your-username/nextdoc4j.git
cd nextdoc4j
# 2. 从 dev 分支拉取新特性分支
git checkout -b feat/sse-virtual-scroll origin/dev
# 3. 本地编译与自动格式化规范
mvn compile
# 4. 提交并推送到个人远程
git commit -m "feat(debug): add virtual scroll support for SSE events"
git push -u origin feat/sse-virtual-scroll开发规范与 Commit 指南
- JDK 基线要求：核心代码需同时兼容 JDK 17 及更高 LTS 版本（JDK 21+）。
- 代码风格标准：严格遵循阿里巴巴《Java开发手册》，变量及方法命名清晰无歧义。
- 自动格式化校验：项目配置了 Spotless 插件，提交前务必在根目录执行
mvn compile修正格式与缩进。 - 文档与注释：所有公共 API（
public方法及接口）必须提供完善的 JavaDoc 注释与参数示例。