docs: enhance contribution documentation with call to action

Copilot · observerw · Copilot · commit 884b3d39b2f1 · 2025-12-20T19:07:24.000Z
Co-authored-by: observerw &lt;20661574+observerw@users.noreply.github.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,177 @@
+# Contributing to LSP Client
+
+Thank you for your interest in contributing to lsp-client! 🎉
+
+## Why Your Contribution Matters
+
+This project is unique in its ambitious scope: **we aim to provide production-ready Python clients for every major language server**, each with its own intricate protocol details, configuration quirks, and containerization requirements.
+
+**We need your help!** The LSP Client project interfaces with numerous upstream projects:
+
+- **Language Servers**: Pyright, Rust-Analyzer, TypeScript, Deno, Pyrefly, and many more to come
+- **LSP Protocol**: The ever-evolving LSP 3.17+ specification with 50+ capabilities
+- **Container Ecosystems**: Docker/Podman images, version management, and build systems
+- **Upstream Dependencies**: npm packages, PyPI distributions, GitHub releases
+
+Each integration requires:
+- Deep understanding of the specific language server's capabilities and behavior
+- Careful testing across different environments (local, container, multi-workspace)
+- Maintaining compatibility as upstream projects evolve
+- Documenting edge cases and configuration options
+
+**No single maintainer can keep up with all these moving parts.** Your expertise with specific language servers, protocols, or use cases is invaluable. Whether you use Rust, Python, TypeScript, or any other language, you have unique insights that can improve this project for everyone.
+
+## How You Can Help
+
+We welcome all kinds of contributions:
+
+### 🚀 Add Support for New Language Servers
+
+Know a language server that would benefit the community? We'd love to integrate it! See our detailed guide:
+
+**→ [How to Add Support for a New LSP Server](docs/contribution/how-to-add-new-servers.md)**
+
+Common servers we'd love to see:
+- **Go**: gopls
+- **Java**: Eclipse JDT, jdtls
+- **C/C++**: clangd
+- **Ruby**: Solargraph, Sorbet
+- **PHP**: Intelephense
+- **And many more!**
+
+### 🧩 Implement LSP Capabilities
+
+The LSP specification includes 50+ capabilities. We've implemented the most common ones, but there's much more to do:
+
+**→ [How to Add a New LSP Capability](docs/contribution/how-to-add-new-capabilities.md)**
+
+Capabilities we need:
+- **textDocument/inlayHint** - inline type hints
+- **textDocument/inlineValue** - debugger inline values
+- **textDocument/colorPresentation** - color picker support
+- **textDocument/linkedEditingRange** - rename refactoring
+- **workspace/symbol** - project-wide symbol search
+- And more from the [LSP 3.17 spec](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/)
+
+### 🐳 Improve Container Support
+
+Help us maintain and improve our container images:
+- Update versions in `registry/wiki.toml`
+- Optimize Dockerfiles for smaller image sizes
+- Add new base images for different environments
+- Improve cross-platform compatibility
+
+### 📚 Documentation & Examples
+
+- Write tutorials for specific use cases
+- Add examples for your favorite language server
+- Improve API documentation
+- Translate documentation to other languages
+
+### 🐛 Bug Reports & Testing
+
+- Report issues with specific language servers
+- Test edge cases in your environment
+- Improve test coverage
+- Share your integration experiences
+
+### 💡 Feature Requests & Discussion
+
+Have ideas for improving the API? Want to discuss architecture decisions? Open an issue or start a discussion!
+
+## Getting Started
+
+### Development Setup
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/observerw/lsp-client.git
+   cd lsp-client
+   ```
+
+2. **Install dependencies** (we recommend [uv](https://github.com/astral-sh/uv)):
+   ```bash
+   uv sync --all-extras
+   ```
+
+3. **Set up pre-commit hooks**:
+   ```bash
+   uv run pre-commit install
+   ```
+
+### Development Workflow
+
+See [AGENTS.md](AGENTS.md) for detailed development commands:
+
+```bash
+# Lint & format
+ruff check --fix && ruff format
+
+# Type checking
+mypy src/
+
+# Run tests
+pytest                    # All tests
+pytest -m unit           # Unit tests only
+pytest -m integration    # Integration tests
+pytest path/to/test.py::test_function  # Single test
+```
+
+### Code Style
+
+- **Python 3.12+** required
+- Use `from __future__ import annotations` in all files
+- Follow [PEP 8](https://peps.python.org/pep-0008/) (enforced by ruff)
+- Full type annotations required (checked by mypy)
+- Write clear docstrings for public APIs
+
+### Commit Guidelines
+
+- Write clear, descriptive commit messages
+- Use conventional commits format:
+  - `feat:` new features
+  - `fix:` bug fixes
+  - `docs:` documentation changes
+  - `test:` test additions/changes
+  - `refactor:` code refactoring
+  - `chore:` maintenance tasks
+
+Examples:
+```
+feat(lsp): add support for gopls language server
+fix(container): resolve path translation issue in Windows
+docs: add tutorial for rust-analyzer integration
+test: add integration tests for multi-root workspaces
+```
+
+## Pull Request Process
+
+1. **Fork the repository** and create a branch from `main`
+2. **Make your changes** following the code style guidelines
+3. **Add tests** for new functionality
+4. **Update documentation** as needed
+5. **Ensure all tests pass**: `pytest`
+6. **Run linting**: `ruff check --fix && ruff format`
+7. **Submit a pull request** with a clear description of your changes
+
+### PR Checklist
+
+- [ ] Tests added/updated and passing
+- [ ] Documentation updated
+- [ ] Code follows style guidelines (ruff, mypy)
+- [ ] Commit messages are clear and descriptive
+- [ ] PR description explains the motivation and changes
+
+## Need Help?
+
+- **Questions?** Open a [Discussion](https://github.com/observerw/lsp-client/discussions)
+- **Bug reports?** Open an [Issue](https://github.com/observerw/lsp-client/issues)
+- **Want to chat?** Reach out in the Issues or Discussions
+
+## Recognition
+
+All contributors will be recognized in our release notes and documentation. We deeply appreciate every contribution, no matter how small!
+
+---
+
+**Remember**: Every language server you help integrate, every capability you implement, and every bug you fix makes this library better for the entire Python community. Your contribution has real impact! 🚀
diff --git a/README.md b/README.md
@@ -107,12 +107,17 @@ Container images are automatically updated weekly to ensure access to the latest
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](docs/contribution/) for details on:
+**We need your help!** 🙌 This project aims to support every major language server, each requiring detailed integration work with upstream projects. Whether you're an expert in Rust, Go, Java, or any other language, your contribution makes a real difference.
 
-- Adding new language server support
-- Extending protocol capabilities
-- Container image updates
-- Development workflow
+### How You Can Contribute
+
+- **🚀 Add new language servers** - Know a language server that should be supported? [Add it!](docs/contribution/how-to-add-new-servers.md)
+- **🧩 Implement LSP capabilities** - Help us support more of the LSP 3.17 spec. [Guide here](docs/contribution/how-to-add-new-capabilities.md)
+- **🐳 Improve containers** - Optimize images, update versions, enhance cross-platform support
+- **📚 Write docs & examples** - Tutorials, use cases, translations
+- **🐛 Report bugs & test** - Share your experiences and edge cases
+
+Every contribution—from fixing typos to implementing complex capabilities—helps the entire Python community. Read our [**Contributing Guide**](CONTRIBUTING.md) to get started!
 
 ## License
 
diff --git a/docs/contribution/how-to-add-new-capabilities.md b/docs/contribution/how-to-add-new-capabilities.md
@@ -1,6 +1,15 @@
 # How to Add a New LSP Capability
 
-This guide details the process for adding new Language Server Protocol (LSP) capabilities to this library. Familiarity with the [LSP 3.17 specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/) and the library's Protocol/Mixin design pattern is recommended.
+**Why this matters**: The Language Server Protocol specification includes 50+ capabilities, from basic autocomplete to advanced refactoring. Each capability you implement opens up new possibilities for developers building intelligent tools. This project needs contributors familiar with different parts of the LSP spec to help achieve complete coverage.
+
+This guide provides a comprehensive walkthrough for adding new LSP capabilities to the library. Whether you're implementing a common capability like `textDocument/inlayHint` or something more specialized, this guide will help you follow the project's architecture patterns.
+
+## Prerequisites
+
+Before starting, familiarize yourself with:
+- The [LSP 3.17 specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/)
+- The library's Protocol/Mixin design pattern (see examples in `src/lsp_client/capability/`)
+- Python's `Protocol` and `runtime_checkable` decorators
 
 ## Design Philosophy
 
@@ -481,3 +490,19 @@ Add a `match` branch for the new capability in the server request dispatch funct
 ## Default Capabilities
 
 Optionally mix in `WithDefaultCapabilities` to enable baseline capabilities (logging and text document synchronization).
+
+---
+
+## Your Contribution Makes a Difference
+
+Implementing LSP capabilities is at the heart of this project. Each capability you add:
+
+- **Enables new use cases** for developers building intelligent tools
+- **Improves compatibility** across different language servers
+- **Advances the Python ecosystem** by making LSP more accessible
+
+The LSP specification is vast, and we can't cover it all alone. Your expertise—whether it's understanding debugger protocols, refactoring operations, or any other LSP feature—is invaluable.
+
+**Questions or stuck on something?** Don't hesitate to open an issue or discussion. We're here to help guide you through the process!
+
+Thank you for contributing to lsp-client! 🎉
diff --git a/docs/contribution/how-to-add-new-servers.md b/docs/contribution/how-to-add-new-servers.md
@@ -1,6 +1,18 @@
 # How to Add Support for a New LSP Server
 
-To add a new LSP server to this project, follow these steps to ensure both client support and containerized deployment are correctly configured.
+**Why this matters**: Language servers are the core of this project. Each new server you add enables Python developers to leverage that language's intelligence—from autocomplete to refactoring—in their tools and workflows. The community needs contributors who understand specific language servers and can help integrate them properly.
+
+This guide shows you how to add complete support for a new LSP server, including both the Python client and containerized deployment.
+
+## Overview
+
+Adding a new language server involves three main steps:
+
+1. **Implement the Python client** - Create a client class with appropriate capability mixins
+2. **Register for automatic versioning** - Enable automated updates from upstream
+3. **Create a container image** - Package the server for isolated, reproducible environments
+
+Let's walk through each step:
 
 ## 1. Implement the Client
 
@@ -60,3 +72,19 @@ ENTRYPOINT ["your-server-binary", "--stdio"]
    ```
 2. Check if `.github/workflows/lsp-servers.yml` and your `ContainerFile` are updated with the latest version.
 3. Commit and push your changes. The GitHub Action will build and push the new image to GHCR.
+
+---
+
+## Your Contribution Expands the Ecosystem
+
+Adding support for a new language server is one of the most impactful contributions you can make:
+
+- **Brings language intelligence to Python developers** working in that language
+- **Reduces integration friction** for tools that need multi-language support
+- **Demonstrates real-world usage patterns** that inform future improvements
+
+The lsp-client project aims to be the go-to solution for LSP integration in Python, and that's only possible with community contributions covering diverse language ecosystems.
+
+**Questions about a specific language server?** Feel free to open an issue or discussion—we're happy to help you navigate the integration process!
+
+Thank you for helping make lsp-client better! 🚀
