# Contributing

Guidelines for submitting changes to LspCpp.

## Getting started

1. Fork and clone the repository.
2. Build with tests enabled (see [Build and test](build-and-test.md)).
3. Make your changes in a feature branch.
4. Run tests and format checks before opening a pull request.

## Code style

### C++ standard

Target **C++17** (`LSPCPP_USE_CPP17=ON` by default). Avoid Boost in library code when a standard-library or standalone-Asio alternative exists.

### Formatting

All C++ code merged to `master` must pass **clang-format**. CI runs the `check-format-cpp` workflow.

Check formatting locally:

```shell
# Discover the clang-format version used in CI from .github/workflows/check-format-cpp.yaml
clang-format --version

# Format a file in place
clang-format -i path/to/file.cpp

# Check without modifying
clang-format --dry-run -Werror path/to/file.cpp
```

The project currently aligns with the clang-format version available on Ubuntu 24.04 (clang-format 18). Re-run format if CI updates the required version.

### Conventions observed in the codebase

- **Namespaces**: `lsp` for library-facing APIs; some legacy types (`RemoteEndPoint`, `WorkingFiles`) live in the global namespace.
- **Headers**: `#pragma once`, includes grouped (project headers, then standard library).
- **Naming**: LSP types follow generated names (`td_initialize`, `Notify_Exit`). Free functions and helpers use `PascalCase` or `snake_case` depending on the surrounding module—match the file you edit.
- **Minimal scope**: Prefer focused changes. Do not reformat unrelated files.

## Pull request checklist

Before requesting review:

- [ ] Code builds with `-DLSPCPP_BUILD_TESTS=ON`
- [ ] `ctest --output-on-failure` passes
- [ ] clang-format applied to changed `.cpp` / `.h` files
- [ ] New LSP types have round-trip or handler tests when applicable
- [ ] Public API changes documented in `docs/engilsh/` or `docs/zh/`
- [ ] Version bumped in `CMakeLists.txt` and `vcpkg.json` only for releases (not every PR)

## Adding LSP protocol support

When adding or updating LSP methods:

1. Define types in the appropriate header under `include/LibLsp/lsp/`.
2. Register parse/serialize handlers in `ProtocolJsonHandler` (see [Protocol types](protocol-types.md)).
3. Add round-trip tests in `tests/lsp_types_roundtrip_tests.cpp` or a version-specific test file.
4. Mention the LSP spec version in the header comment if the method is version-gated.

## Dependency changes

Bundled dependencies live in `third_party/`. Prefer updating via git submodules rather than vendoring arbitrary snapshots.

To use system/vcpkg packages instead:

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

Document new CMake options in `docs/engilsh/user/build-and-install.md`, `docs/zh/user/build-and-install.md`, and the root `README.md`.

## Releases

LspCpp uses [semantic versioning](https://semver.org/). Release steps:

1. Update `LSPCPP_VERSION` in `CMakeLists.txt`.
2. Update `version-semver` in `vcpkg.json`.
3. Tag `vX.Y.Z` on GitHub.
4. Publish release notes listing API or behavior changes.

## License

Contributions are accepted under the project **MIT** license. By submitting a pull request, you agree that your contributions will be licensed under MIT.

## Reference

Some code originates from [cquery](https://github.com/cquery-project/cquery). Preserve existing copyright notices when modifying those files.