贡献指南

提示

找一帮你喜欢的、真正靠谱的人，一起做有意思的事

首先，感谢你抽出宝贵的时间参与到（或者有意向参与到） JAP 的贡献！

JAP 是一款开源的登录认证中间件，基于模块化设计，为所有需要登录认证的 WEB 应用提供一套标准的技术解决方案，开发者可以基于 JAP 适配绝大多数的 WEB 系统（自有系统、联邦协议），就像集成 JustAuth (opens new window) 一样，简单方便。

JAP 的成长离不开大家的支持，如果你愿意为 JAP 贡献代码或提供建议，请阅读以下内容。

# 可以贡献哪些内容？

你可以对以下内容（不仅限于此）进行贡献：

修复bug（已打开的 Issue（gitee issues (opens new window) | github issues (opens new window)）或者是你发现的 BUG）
完善代码注释
添加单元测试
代码逻辑优化
新功能开发
编写/翻译文档
本文档站中出现的问题
本文档站需要完善的内容
对本文档站的建议
参与问卷调查：

代码贡献须知

在你提交代码时请确定你所贡献的代码不存在协议冲突/不兼容的情况

你可以从以下两个方面检查你的代码：

是否新增了第三方依赖库？如果新增了第三方依赖库，其 LICENSE 是否兼容 LGPL-3.0？（LICENSE 兼容，请参考：开源许可证兼容性指南 - 使用库的兼容性列表 (opens new window)）
是否参考/借鉴/复制了其他开源项目的代码？被引用的代码所属项目的 LICENSE 是否兼容 LGPL-3.0？（LICENSE 兼容，请参考：开源许可证兼容性指南 - 合并/修改代码的许可证兼容性列表 (opens new window)）

如果你的代码或者代码中新引入的依赖项与 LGPL-3.0 不兼容，非常抱歉，我们可能不会合并你的代码。

如何反馈一个高质量的问题？

提供问题的清晰描述，描述具体缺失、过时、错误的内容或者需要改进的文字。
解释该问题对用户的影响。
将给定问题的范围限定在一个具体内容、任务。如果问题牵涉的领域较大，可以将其分解为多个小一点的问题。例如："文档需要优化" 是一个过于宽泛的问题，而 "XX开发指南缺少对XXX步骤的介绍" 就是一个足够具体的、可操作的问题。
搜索现有问题的列表（gitee issues (opens new window) | github issues (opens new window)，查看是否已经有相关的或者类似的问题已被记录。
如果新问题与某其他问题或 PR 有关联，可以使用其完整 URL 或带 # 字符的 PR 编号来引用它。

如何在社群中高效提问？

社群（QQ群、微信群、Gitter等）中消息比较多而杂，为了更好的解决你的问题，我们建议优先选择 issue（gitee issues (opens new window) | github issues (opens new window)
在社群中提问时尽量采用完整、清晰的描述，不建议此类问题，比如：“xx怎么用？”、“为什么我的报错？”、或者直接发一张异常截图不加描述，对于此类问题，我们可能会选择忽略。
提问前推荐阅读《提问的智慧》 (opens new window)、《如何向开源社区提问题》 (opens new window) 和《如何有效地报告 Bug》 (opens new window)、《如何向开源项目提交无法解答的问题》 (opens new window)，更好的问题更容易获得帮助。

Pull Request 须知

提交 PR 前，请务必对自己的代码进行格式化。
提交 PR 前请 rebase，确保 commit 记录的整洁。
提交 PR 前请先对代码进行 review。
确保 PR 是提交到 dev 分支，而不是 master 分支。如果你提交的 PR 许久未合并，请确认你是否将 PR 提到了其他分支。
如果是修复未公开的 bug，请在 PR 中给出描述信息，参考：A Note About Git Commit Messages (opens new window)。
如果是修复已存在的 issue，请在描述中引用原文，例如: “Resolves #issueid”。

请使用英文描述
commit 信息要以 类型: [模块名] 描述信息 的形式填写，例如 feat: [jap-social] add xx feature，”类型“可选如下：
- refactor：重构
- feat：新功能
- docs：文档
- test：测试
- fix：bug/issue
- change：修改
commit 完成后，将代码 push 到 fork 分支
请使用具有真实含义的内容
请确保单次 “message” 的内容尽量不超过 100 字
你可以在提交时使用 emoji 表情，使用方式参考：gitmoji (opens new window) | Emoji Cheat Sheet (opens new window)
参考：A Note About Git Commit Messages (opens new window)

关于包名，请以拥有实际含义的名字命名，不可使用无意义的字母排列或者中文拼音。
- 新模块务必以com.fujieid.jap.模块名 命名，比如：com.fujieid.jap.social。
- 新业务包务必以com.fujieid.jap.模块名.相关业务 命名，比如：com.fujieid.jap.social.config。
关于类名，请以拥有实际含义的名字命名，不可使用无意义的字母排列或者中文拼音。
关于方法名，请以拥有实际含义的名字命名，不可使用无意义的字母排列或者中文拼音。
关于注释，对于简单的方法，可以不添加注释，对于存在复杂逻辑或者有必要强调说明的方法、参数，必须添加注释，注释必须做到精简、准确。
关于文档，我们这不是论文，所以请使用简单、干练或通俗易懂的文案，尽量不要使用大量的专业名词进行堆砌，加大开发者的阅读理解难度。
其他代码规范，请遵循阿里巴巴编码规约。

对于有必要书写 doc 的方法、类、参数，请描述清晰。
如果对方法添加了注释，请务必对方法的参数、返回值、异常等进行解释描述。
其他规范请参考：https://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html (opens new window)

Last Updated: 2021/10/07, 18:03:43