Copilot commented on code in PR #3369: URL: https://github.com/apache/kvrocks/pull/3369#discussion_r2796549541
########## AGENTS.md: ########## @@ -0,0 +1,163 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (e.g., Claude Code, Cursor, ChatGPT Codex, Gemini) when working with code in this repository. + +While working on Apache Kvrocks, please remember: + +- Always use English in code and comments. +- Only add meaningful comments when the code's behavior is difficult to understand. +- Only add meaningful tests when they actually verify internal behaviors; otherwise, don't create them unless requested. Review Comment: The quick tips say to add tests only when they verify “internal behaviors” and otherwise not create them unless requested. This conflicts with the later “Testing Guidelines” section (which emphasizes command/behavior verification) and encourages brittle tests. Consider rephrasing this to focus on externally observable behavior/regressions and to add/update tests alongside behavior changes when appropriate. ```suggestion - Add or update tests to cover externally observable behavior and regressions when you change or add functionality. ``` ########## AGENTS.md: ########## @@ -0,0 +1,163 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (e.g., Claude Code, Cursor, ChatGPT Codex, Gemini) when working with code in this repository. + +While working on Apache Kvrocks, please remember: + +- Always use English in code and comments. +- Only add meaningful comments when the code's behavior is difficult to understand. +- Only add meaningful tests when they actually verify internal behaviors; otherwise, don't create them unless requested. +- Always run the formatter before submitting changes. + +## Build and Development Commands + +### Building + +```bash +# Build kvrocks and utilities +./x.py build # Build to ./build directory +./x.py build -j N # Build with N parallel jobs +./x.py build --unittest # Build with unit tests +./x.py build -DENABLE_OPENSSL=ON # Build with TLS support +./x.py build --ninja # Use Ninja build system +./x.py build --skip-build # Only run CMake configure +./x.py build -DCMAKE_BUILD_TYPE=Debug # Debug build + +# Run a local server +./build/kvrocks -c kvrocks.conf + +# Fetch dependencies +./x.py fetch-deps # Fetch dependency archives +``` + +### Testing + +```bash +# Build and run C++ unit tests +./x.py build --unittest +./x.py test cpp + +# Run Go integration tests +./x.py test go + +# Run specific Go test by path +./x.py test go tests/gocase/unit/... +``` + +### Lint + +You must run the formatter and linters before submitting code changes. This ensures code quality and consistency across the project. It requires installing `clang-format`, `clang-tidy`, and `golangci-lint` locally. Please refer to the CONTRIBUTING.md for setup instructions. + +```bash +# Format code (must pass before submitting) +./x.py format + +# Check code format (fails if not formatted) +./x.py check format + +# Run clang-tidy +./x.py check tidy + +# Run golangci-lint for Go tests +./x.py check golangci-lint +``` + +## Architecture Overview + +Apache Kvrocks is a distributed key-value NoSQL database compatible with the Redis protocol, using RocksDB as its storage engine. + +### Core Structure + +- **`src/server/`**: Main server orchestration, connection handling, and worker threads. The `Server` class manages the event loop, worker threads, and coordinates all components. +- **`src/storage/`**: RocksDB integration layer. Key classes: + - `Storage`: Manages RocksDB instance, column families, and write batches + - `Context`: Passes snapshot and batch between APIs for transactional consistency +- **`src/commands/`**: Redis protocol command implementations. Each command type has a corresponding `Commander` subclass. +- **`src/types/`**: Redis data structure implementations (String, Hash, List, Set, ZSet, Stream, etc.) +- **`src/cluster/`**: Cluster management, slot migration, and replication. +- **`src/search/`**: Full-text search and vector search (HNSW) implementation. +- **`src/config/`**: Server configuration parsing and management. +- **`src/cli/`**: Command-line interface utilities. +- **`src/common/`**: Shared utilities and helper functions. +- **`src/stats/`**: Statistics and metrics collection. + +### Key Patterns + +- **Column Families**: 8 column families are used - PrimarySubkey, Metadata, SecondarySubkey, PubSub, Propagate, Stream, Search, Index. +- **Command Registration**: Commands are registered via the `REDIS_REGISTER_COMMANDS` macro with flags like `kCmdWrite`, `kCmdReadOnly`, `kCmdBlocking`, etc. +- **Write Batch with Index**: Used for transactional mode to group writes before commit. +- **Worker Thread Model**: Libevent-based async I/O with dedicated worker threads. +- **Namespace Isolation**: Token-based multi-tenancy using the `__namespace` column family. Review Comment: “Namespace Isolation” is described as using the `__namespace` column family, but in the codebase `__namespace` is the default namespace string (kDefaultNamespace) and namespace tokens are stored under `__namespace_keys__` in the Propagate column family. This should be corrected to avoid misguiding contributors about the storage layout. ```suggestion - **Namespace Isolation**: Token-based multi-tenancy using the default namespace string `__namespace` (`kDefaultNamespace`); namespace tokens are stored under `__namespace_keys__` in the Propagate column family. ``` ########## AGENTS.md: ########## @@ -0,0 +1,163 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (e.g., Claude Code, Cursor, ChatGPT Codex, Gemini) when working with code in this repository. + +While working on Apache Kvrocks, please remember: + +- Always use English in code and comments. +- Only add meaningful comments when the code's behavior is difficult to understand. +- Only add meaningful tests when they actually verify internal behaviors; otherwise, don't create them unless requested. +- Always run the formatter before submitting changes. + +## Build and Development Commands + +### Building + +```bash +# Build kvrocks and utilities +./x.py build # Build to ./build directory +./x.py build -j N # Build with N parallel jobs +./x.py build --unittest # Build with unit tests +./x.py build -DENABLE_OPENSSL=ON # Build with TLS support +./x.py build --ninja # Use Ninja build system +./x.py build --skip-build # Only run CMake configure +./x.py build -DCMAKE_BUILD_TYPE=Debug # Debug build + +# Run a local server +./build/kvrocks -c kvrocks.conf + +# Fetch dependencies +./x.py fetch-deps # Fetch dependency archives +``` + +### Testing + +```bash +# Build and run C++ unit tests +./x.py build --unittest +./x.py test cpp + +# Run Go integration tests +./x.py test go + +# Run specific Go test by path +./x.py test go tests/gocase/unit/... +``` + +### Lint + +You must run the formatter and linters before submitting code changes. This ensures code quality and consistency across the project. It requires installing `clang-format`, `clang-tidy`, and `golangci-lint` locally. Please refer to the CONTRIBUTING.md for setup instructions. Review Comment: This section references “CONTRIBUTING.md” for setup instructions, but there is no CONTRIBUTING.md in the repository root (or elsewhere). Please update the reference to the correct location (e.g., README section, website link, or actual path) so the guidance doesn’t send contributors to a dead file. ```suggestion You must run the formatter and linters before submitting code changes. This ensures code quality and consistency across the project. It requires installing `clang-format`, `clang-tidy`, and `golangci-lint` locally. Please refer to the project documentation (for example, the README or official docs) for setup instructions. ``` ########## AGENTS.md: ########## @@ -0,0 +1,163 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (e.g., Claude Code, Cursor, ChatGPT Codex, Gemini) when working with code in this repository. + +While working on Apache Kvrocks, please remember: + +- Always use English in code and comments. +- Only add meaningful comments when the code's behavior is difficult to understand. +- Only add meaningful tests when they actually verify internal behaviors; otherwise, don't create them unless requested. +- Always run the formatter before submitting changes. + +## Build and Development Commands + +### Building + +```bash +# Build kvrocks and utilities +./x.py build # Build to ./build directory +./x.py build -j N # Build with N parallel jobs +./x.py build --unittest # Build with unit tests +./x.py build -DENABLE_OPENSSL=ON # Build with TLS support +./x.py build --ninja # Use Ninja build system +./x.py build --skip-build # Only run CMake configure +./x.py build -DCMAKE_BUILD_TYPE=Debug # Debug build + +# Run a local server +./build/kvrocks -c kvrocks.conf + +# Fetch dependencies +./x.py fetch-deps # Fetch dependency archives +``` + +### Testing + +```bash +# Build and run C++ unit tests +./x.py build --unittest +./x.py test cpp + +# Run Go integration tests +./x.py test go + +# Run specific Go test by path +./x.py test go tests/gocase/unit/... +``` + +### Lint Review Comment: The markdown header has trailing whitespace (`### Lint `). Consider removing the trailing space to avoid markdown/style linters flagging it. ```suggestion ### Lint ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
