参与项目

无论是普通用户还是开发者，我们都非常欢迎你参与海豹的开发，一起努力让海豹变得更好。

海豹的所有源代码都托管在海豹开源组织 GitHub 下，每个模块都存放在对应的仓库中，可阅读对应仓库的 Readme 获取更多信息。

几个比较重要的仓库：

核心：海豹的 Go 后端代码仓库，这个仓库也作为海豹的主仓库，Bug 可反馈在该仓库的 issue 中；
UI：海豹的前端代码，基于 Vue3 + ElementPlus 开发；
手册（新）：海豹新版官方手册（即当前的手册）的源码，如对手册有什么改进内容可以在该项目提交 pr；
构建：海豹的自动构建仓库，用于自动化发布海豹的每日构建包与 Release；
……

如何参与项目？

Bug 反馈、功能建议

所有的 Bug 和功能建议都可反馈在核心仓库的 issue 中，按照模板填写可方便开发组快速定位问题。

提示：无法访问 GitHub？

受限于各种原因，不是所有人都能顺利访问 GitHub，如有 Bug 可以加入官方群进行反馈。但如果有条件，我们还是建议在 GitHub 向开发组反馈问题。

提交修改

欢迎各种类型的 pr 提交，可以帮助改进代码，增加功能，也可以是完善文档等等。向对应仓库发起 pr 即可。

贡献指南

海豹是一个开源项目，代码的开发、文档的编写等都涉及到开发者之间的协作。共同遵循一些原则有助于包括编写、维护、审核在内的每一个开发者。请在提 Pull Request 之前花几分钟来阅读以下内容。

Pull Request

提交 Pull Request 时，需要遵循 「一个模块的修改对应一个 PR」 的原则。具体来说，如果是代码修改（如对 core 仓库的修改），一个 PR 仅包含一个完整功能的实现。如果是文档修改，则一个 PR 包含对某一个章节的修改。不要将对多个不相关模块的修改，合并在一个巨石 PR 中一并提交。

Pull Request 的标题是有意义的，应当用 「简短但具体的一句话」 概括本 PR 的修改内容。使用如 feat: 完成了 xx 功能，fix: 修复了 xx 原因导致的 xx 问题 等比较具体的描述，而不是 改进功能，修复错误 等非常宽泛的提示。这有助于后续其他开发者在审核及回看历史时大致了解这个 PR 的内容，也有助于在版本发布时总结本次迭代的影响范围。

如果你发现很难用一句具体的话进行概括，或者不得不用「和」等连词连接多个部分，你的 PR 有可能还能进一步拆分，请认真检查。

此外，影响很大的变更最好不要直接提交，最好先以 issue 等形式等先进行相关讨论，这样可以避免出现重复修改的情况。

在提交 Pull Request 之前，请确认以下步骤都已完成：

基于 最新主干代码 做修改（通常是 master 分支）。
代码的修改确认是完整可运行的，且在本地已自测可用。如果不是完整修改，请以 Draft PR 的方式提交来分享进度。
能够通过相应仓库的测试和 Lint 检查。通常各个仓库都会有工作流进行自动检测，但请在本地提前进行检查。
提交信息清晰规范，便于追踪改动内容。应当遵循惯例格式，便于后续维护和版本管理。
代码风格保持一致，遵循各仓库已有的代码规范。

手册

海豹手册是向用户提供的官方使用指南，我们希望手册能够尽量解决海豹的使用问题，但同时也希望手册是便于维护的，不要带来不必要的维护压力。目前来说，我们希望：

手册属于海豹：海豹手册是介绍海豹使用的相关指南，主要目标在于介绍诸如指令使用、扩展系统等海豹自己功能的使用和帮助。
- 外部内容仅作引导：以 QQ 对接为例，仅介绍大体流程和指向相应对接方式自己的手册。QQ 平台的特殊现状导致变动频繁，应当指引用户查看对接方自己的手册以获得最新提示，不要在海豹手册中介绍过时内容。
- 不要介绍敏感内容：诸如「选择哪一家服务器」（涉及金钱），「某对接方式的签名问题」（涉及侵权），「如何访问 GitHub」等不适当的话题，不应在手册中介绍。
手册是准确的：手册介绍内容时务必准确，新版本的变动都应具体到版本号，表述不要模棱两可。编者本身都不清楚的内容，宁可跳过不写也不要误导用户。
- 一些历史遗漏内容也没有很好的做到这一点，但由于维护压力目前只能以在章节前进行警告的方式保留，引以为戒。
手册是规范的：手册措辞使用规范的书面语，不要太过口语化。排版遵循中文文案排版指北的规范。
- 合理划分章节与子章节，各小节之间内容层次分明。
- 适当使用截图、图表等辅助说明复杂操作。对于图片，需要特别确认在 PC 端和移动端，日间和夜间模式下均可良好展示。
- 保持术语一致性，同一概念在全手册中应使用相同的表达方式。
- 重要提示和注意事项应使用相应记号突出显示。但不要滥用记号导致出现提示比正文还多的情况。