# 贡献指南

向 LspCpp 提交变更的指南。

## 入门

1. Fork 并 clone 仓库。
2. 启用测试进行构建（见[构建与测试](build-and-test.md)）。
3. 在 feature 分支上修改。
4. 打开 pull request 前运行测试与格式检查。

## 代码风格

### C++ 标准

目标 **C++17**（默认 `LSPCPP_USE_CPP17=ON`）。库代码中若有标准库或 standalone-Asio 替代方案，避免使用 Boost。

### 格式化

合并到 `master` 的全部 C++ 代码必须通过 **clang-format**。CI 运行 `check-format-cpp` 工作流。

本地检查格式：

```shell
# 从 .github/workflows/check-format-cpp.yaml 查看 CI 使用的 clang-format 版本
clang-format --version

# 就地格式化文件
clang-format -i path/to/file.cpp

# 仅检查不修改
clang-format --dry-run -Werror path/to/file.cpp
```

项目当前与 Ubuntu 24.04 可用的 clang-format 版本对齐（clang-format 18）。若 CI 更新所需版本，请重新格式化。

### 代码库中的约定

- **命名空间**：面向库的 API 使用 `lsp`；部分遗留类型（`RemoteEndPoint`、`WorkingFiles`）在全局命名空间。
- **头文件**：`#pragma once`，include 分组（项目头文件，然后标准库）。
- **命名**：LSP 类型遵循生成名（`td_initialize`、`Notify_Exit`）。自由函数与辅助工具依模块使用 `PascalCase` 或 `snake_case` — 匹配你编辑的文件。
- **最小范围**：优先聚焦变更。不要格式化无关文件。

## Pull request 检查清单

请求 review 前：

- [ ] 代码在 `-DLSPCPP_BUILD_TESTS=ON` 下可构建
- [ ] `ctest --output-on-failure` 通过
- [ ] 对已修改的 `.cpp` / `.h` 文件应用 clang-format
- [ ] 新 LSP 类型在适用时有往返或 handler 测试
- [ ] 公共 API 变更已在 `docs/engilsh/` 或 `docs/zh/` 中文档化
- [ ] 仅在发布时 bump `CMakeLists.txt` 和 `vcpkg.json` 中的版本（不是每个 PR）

## 添加 LSP 协议支持

添加或更新 LSP method 时：

1. 在 `include/LibLsp/lsp/` 下适当头文件中定义类型。
2. 在 `ProtocolJsonHandler` 中注册解析/序列化 handler（见[协议类型](protocol-types.md)）。
3. 在 `tests/lsp_types_roundtrip_tests.cpp` 或版本专用测试文件中添加往返测试。
4. 若 method 受版本限制，在头文件注释中注明 LSP 规范版本。

## 依赖变更

捆绑依赖在 `third_party/`。优先通过 git submodule 更新，而非随意 vendoring 快照。

改用系统/vcpkg 包：

- `USE_SYSTEM_RAPIDJSON=ON`
- `USE_EXTERNAL_ASIO=ON`
- `USE_EXTERNAL_IXWEBSOCKET=ON`

在 `docs/engilsh/user/build-and-install.md`、`docs/zh/user/build-and-install.md` 和根 `README.md` 中文档化新 CMake 选项。

## 发布

LspCpp 使用[语义化版本](https://semver.org/)。发布步骤：

1. 更新 `CMakeLists.txt` 中的 `LSPCPP_VERSION`。
2. 更新 `vcpkg.json` 中的 `version-semver`。
3. 在 GitHub 上打 tag `vX.Y.Z`。
4. 发布说明中列出 API 或行为变更。

## 许可证

贡献在项目的 **MIT** 许可证下接受。提交 pull request 即表示你同意贡献以 MIT 许可。

## 参考

部分代码源自 [cquery](https://github.com/cquery-project/cquery)。修改这些文件时请保留现有版权声明。