How to Contribute - liuli-neko/NekoProtoTools GitHub Wiki

💖 Thank you for your interest in contributing to NekoProtoTools! 💖

We welcome contributions of all kinds, from bug reports and documentation improvements to new features and backend implementations. Our goal is to make NekoProtoTools a powerful yet simple tool for C++ developers dealing with protocols, serialization, and RPC.

Guiding Philosophy

Before diving into specific areas, it's helpful to understand the core philosophy behind NekoProtoTools:

  • Simplify Complexity: Abstract away the tedious and error-prone parts of serialization, protocol definition, and communication. Developers should focus on their application logic.
  • Leverage Modern C++: Utilize C++17/C++20 features and template metaprogramming to reduce boilerplate, enhance type safety, and improve compile-time checks.
  • Seamless Integration: Make using serialized data or calling remote procedures feel as natural as accessing a C++ class member or calling a local function. Hide the underlying transmission and parsing details whenever possible.
  • Composability and Extensibility: Design components (Serializers, Protocols, Communication, RPC) to be modular and interchangeable. Protocols should work with any serializer; communication should support various transport backends. This allows for maximum flexibility and reuse.

Contributions that align with this philosophy are highly encouraged!

Ways to Contribute

1. Reporting Issues & Suggesting Features

  • Found a bug? Have an idea for a new feature or improvement? Please open an issue on GitHub.
  • Provide as much detail as possible: what you were trying to do, what happened, what you expected, library version, platform, and ideally, a minimal reproducible code example.

2. Improving Documentation

  • Clear documentation is crucial! If you find parts of the Wiki unclear, incomplete, or incorrect, please feel free to suggest changes or submit a PR with improvements.
  • Adding more examples to the Wiki or source code comments is always welcome.

3. Enhancing and Extending Serialization Backends

This is a core area where contributions can have a big impact.

  • Adding New Serializer Backends:
    • Implement support for other popular formats like MessagePack, Protobuf (potentially just integrating with the official library), BSON, CBOR, etc.
    • Follow the interfaces defined in <nekoproto/proto/serializer_base.hpp> and refer to the Implementing a Custom Serializer guide.
  • Improving Existing Serializer Backends:
    • JSON (SIMDJson): Currently only supports deserialization. A major contribution would be to implement efficient serialization (output) using SIMDJson.
    • JSON (RapidJSON): While generally robust, performance optimizations or ensuring compatibility with edge cases are welcome.
    • XML (RapidXML): Currently only supports deserialization. Implementing serialization (output) support using RapidXML (or another suitable XML library) would be valuable.
    • Binary: The current implementation is functional but could be improved. Contributions could include:
      • Robustness: Enhancing error handling during deserialization (e.g., preventing crashes on malformed input).
      • Schema/Versioning: Adding optional features for handling schema evolution or versioning within the binary format.
      • Optimizations: Reducing size or improving speed where possible.

4. Extending Core Features (Built on Serialization)

These components leverage the serialization layer:

  • Protocol Management (IProto/ProtoFactory):
    • Optimize performance or memory usage.
    • Enhance reflection capabilities (if feasible without significant overhead).
    • Improve protocol table synchronization features.
  • Communication Layer (ProtoStreamClient/ProtoDatagramClient):
    • Implement support for more Ilias transport backends (e.g., WebSockets, QUIC, if Ilias provides them).
    • Improve the atomicity and error handling during send/receive operations (addressing TODOs).
    • Add configuration options (e.g., timeouts, buffer sizes).
  • JSON-RPC Implementation:
    • Ensure full compliance with JSON-RPC 2.0 and potentially 1.0 specifications.
    • Implement optional extensions to the JSON-RPC protocol.
    • Improve error reporting and handling.
    • Enhance flexibility in transport usage (beyond the default TCP).

5. Adding Tests and Examples

  • Increase test coverage with more unit tests and integration tests for all components, especially serializers and communication edge cases.
  • Provide more real-world examples demonstrating how to use different features together.

Submitting Changes (Pull Requests)

  1. Fork the Repository: Create your own fork of liuli-neko/NekoProtoTools.
  2. Create a Branch: Make a new branch in your fork for your changes (e.g., feature/add-msgpack-serializer, fix/binary-deserialization-bug).
  3. Make Your Changes: Write your code, ensuring it aligns with the library's philosophy and coding style (if one is formally defined later).
  4. Add Tests: Include unit tests for any new features or bug fixes.
  5. Update Documentation: Update the Wiki or code comments as necessary.
  6. Ensure Build Passes: Make sure the code compiles and all tests pass (xmake build, xmake test).
  7. Commit Your Changes: Use clear and descriptive commit messages.
  8. Push to Your Fork: Push your branch to your GitHub fork.
  9. Open a Pull Request: Submit a Pull Request from your branch to the main branch of the original liuli-neko/NekoProtoTools repository. Provide a clear description of your changes in the PR.

We'll review your PR as soon as possible. Thank you for helping make NekoProtoTools better!