wgtmac commented on code in PR #237: URL: https://github.com/apache/iceberg-cpp/pull/237#discussion_r2374973926
########## mkdocs/docs/index.md: ########## @@ -0,0 +1,199 @@ +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. +--> + +# Contributing + +We welcome contributions to Apache Iceberg! To learn more about contributing to Apache Iceberg, please refer to the official Iceberg contribution guidelines. These guidelines are intended as helpful suggestions to make the contribution process as seamless as possible, and are not strict rules. + +If you would like to discuss your proposed change before contributing, we encourage you to visit our Community page. There, you will find various ways to connect with the community, including Slack and our mailing lists. Alternatively, you can open a new issue directly in the GitHub repository. + +For first-time contributors, feel free to check out our good first issues for an easy way to get started. + +## Contributing to Iceberg C++ + +The Iceberg C++ Project is hosted on GitHub at [https://github.com/apache/iceberg-cpp](https://github.com/apache/iceberg-cpp). + +### Development Setup + +#### Prerequisites + +- CMake 3.25 or higher +- C++23 compliant compiler (GCC 11+, Clang 14+, MSVC 2022+) +- Git + +#### Building from Source + +Clone the repository for local development: + +```bash +git clone https://github.com/apache/iceberg-cpp.git +cd iceberg-cpp +``` + +Build the core libraries: + +```bash +cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DICEBERG_BUILD_STATIC=ON -DICEBERG_BUILD_SHARED=ON +cmake --build build +ctest --test-dir build --output-on-failure +cmake --install build +``` + +Build with bundled dependencies: + +```bash +cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DICEBERG_BUILD_BUNDLE=ON +cmake --build build +ctest --test-dir build --output-on-failure +cmake --install build +``` + +### Code Standards + +#### C++ Coding Standards + +We follow modern C++ best practices: + +- **C++23 Standard**: Use C++23 features where appropriate +- **Naming Conventions**: + - Classes: `PascalCase` (e.g., `TableScanBuilder`) + - Functions: `snake_case` (e.g., `find_field_by_name`) + - Variables: `snake_case` (e.g., `file_io`) + - Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRIES`) +- **Memory Management**: Prefer smart pointers (`std::unique_ptr`, `std::shared_ptr`) +- **Error Handling**: Use `Result<T>` types for error propagation +- **Documentation**: Use Doxygen-style comments for public APIs + +#### API Compatibility + +It is important to keep the C++ public API compatible across versions. Public methods should have no leading underscores and should not be removed without deprecation notice. + +If you want to remove a method, please add a deprecation notice: + +```cpp +[[deprecated("This method will be removed in version 2.0.0. Use new_method() instead.")]] +void old_method(); +``` + +#### Code Formatting + +We use `clang-format` for code formatting. The configuration is defined in `.clang-format` file. + +Format your code before submitting: + +```bash +clang-format -i src/**/*.{h,cc} +``` + +### Testing + +#### Running Tests + +Run all tests: + +```bash +ctest --test-dir build --output-on-failure +``` + +Run specific test: + +```bash +ctest --test-dir build -R test_name +``` + +#### Test Coverage + +We aim for high test coverage. Run tests with coverage: + +```bash +cmake -S . -B build -DICEBERG_BUILD_COVERAGE=ON Review Comment: We don't have this yet. Perhaps an AI illusion? -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
