CONTRIBUTING.md - paimon-cpp - Git at Google


            
            <!--

            
              ~ 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 to Apache Paimon C++


            Thank you for your interest in contributing to Paimon C++! This document explains how to get started.


            ---


            ## Reporting Issues


            If you find a bug or want to request a feature, please open an [issue](https://github.com/apache/paimon-cpp/issues/new). Include as much detail as possible — steps to reproduce, expected vs. actual behavior, environment info, etc.


            ---


            ## Commit Messages and Pull Request Titles


            Use the [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages and pull request titles:


            ```text

            
            <type>(<optional-scope>): <description>

            
            ```


            Examples:


            ```text

            
            feat(parquet): support page-level bitmap filtering

            
            fix: handle non-contiguous row ranges

            
            test(executor): add shutdown coverage

            
            docs: update the build instructions

            
            ```


            Choose a type and optional scope that accurately describe the change. Keep the description concise and write it in the imperative mood. A pull request title should summarize the complete change and use the same format.


            ---


            ## Submitting Pull Requests


            1. **Fork** the repository and create a feature branch from `main`.

            
            2. Make your changes following the [Code Style Guide](docs/code-style.md).

            
            3. Add or update tests for the functionality you changed.

            
            4. Ensure all checks pass.

            
            5. Open a pull request against `main`. Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md).


            When addressing review feedback or adding follow-up changes to an open pull request, prefer a separate commit instead of amending and force-pushing existing commits. This makes the incremental diff easier for reviewers to inspect. Rewrite existing commits only when a maintainer explicitly requests it.


            ### PR Checklist


            Before submitting, please verify:


            - [ ] Code compiles without warnings under `-Wall` (enabled by default in the build system).

            
            - [ ] `pre-commit run --all-files` passes.

            
            - [ ] New / modified public APIs are marked with `PAIMON_EXPORT`.

            
            - [ ] Every new file has the Apache 2.0 license header.

            
            - [ ] Error handling uses `Status` / `Result<T>` — no exceptions.

            
            - [ ] New utility code checks for existing helpers before reinventing (see the [utility reference](docs/code-style.md#reuse-existing-utilities)).

            
            - [ ] Tests are added or updated for the changed functionality.

            
            - [ ] PR description follows the [template](.github/PULL_REQUEST_TEMPLATE.md).


            ---


            ## Development Setup


            ### Prerequisites


            - **C++17** compatible compiler (GCC recommended)

            
            - **CMake** ≥ 3.22

            
            - **Python 3** (for linting scripts and pre-commit)


            ---


            ## Code Style


            Please read the full [Code Style Guide](docs/code-style.md) before writing code. Key highlights:


            - **Formatting**: Google C++ Style base, 100-column limit, 4-space indent. Let clang-format handle it.

            
            - **Error handling**: Use `Status` / `Result<T>` and project macros (`PAIMON_RETURN_NOT_OK`, `PAIMON_ASSIGN_OR_RAISE`). No exceptions.

            
            - **Naming**: PascalCase for classes and methods, snake_case for variables, trailing `_` for members.

            
            - **Headers**: `#pragma once`, includes ordered by category, Apache 2.0 license header on every file.

            
            - **Factory pattern**: Use `static Create()` + private constructor when construction can fail.

            
            - **Testing**: Google Test, `ASSERT_*` preferred over `EXPECT_*`, test files named `*_test.cpp` next to source.


            ---


            ## Dev Containers


            We provide Dev Container configuration file templates for VS Code:


            ```bash

            
            cd .devcontainer

            
            cp Dockerfile.template Dockerfile

            
            cp devcontainer.json.template devcontainer.json

            
            ```


            Then select **Dev Containers: Reopen in Container** from VS Code's Command Palette.


            If you make improvements that could benefit all developers, please update the template files and submit a pull request.


            ---


            ## License


            By contributing to Paimon C++, you agree that your contributions will be licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
	<!--
	~ 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 to Apache Paimon C++

	Thank you for your interest in contributing to Paimon C++! This document explains how to get started.

	---

	## Reporting Issues

	If you find a bug or want to request a feature, please open an [issue](https://github.com/apache/paimon-cpp/issues/new). Include as much detail as possible — steps to reproduce, expected vs. actual behavior, environment info, etc.

	---

	## Commit Messages and Pull Request Titles

	Use the [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages and pull request titles:

	```text
	<type>(<optional-scope>): <description>
	```

	Examples:

	```text
	feat(parquet): support page-level bitmap filtering
	fix: handle non-contiguous row ranges
	test(executor): add shutdown coverage
	docs: update the build instructions
	```

	Choose a type and optional scope that accurately describe the change. Keep the description concise and write it in the imperative mood. A pull request title should summarize the complete change and use the same format.

	---

	## Submitting Pull Requests

	1. Fork the repository and create a feature branch from `main`.
	2. Make your changes following the [Code Style Guide](docs/code-style.md).
	3. Add or update tests for the functionality you changed.
	4. Ensure all checks pass.
	5. Open a pull request against `main`. Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md).

	When addressing review feedback or adding follow-up changes to an open pull request, prefer a separate commit instead of amending and force-pushing existing commits. This makes the incremental diff easier for reviewers to inspect. Rewrite existing commits only when a maintainer explicitly requests it.

	### PR Checklist

	Before submitting, please verify:

	- [ ] Code compiles without warnings under `-Wall` (enabled by default in the build system).
	- [ ] `pre-commit run --all-files` passes.
	- [ ] New / modified public APIs are marked with `PAIMON_EXPORT`.
	- [ ] Every new file has the Apache 2.0 license header.
	- [ ] Error handling uses `Status` / `Result<T>` — no exceptions.
	- [ ] New utility code checks for existing helpers before reinventing (see the [utility reference](docs/code-style.md#reuse-existing-utilities)).
	- [ ] Tests are added or updated for the changed functionality.
	- [ ] PR description follows the [template](.github/PULL_REQUEST_TEMPLATE.md).

	---

	## Development Setup

	### Prerequisites

	- C++17 compatible compiler (GCC recommended)
	- CMake ≥ 3.22
	- Python 3 (for linting scripts and pre-commit)

	---

	## Code Style

	Please read the full [Code Style Guide](docs/code-style.md) before writing code. Key highlights:

	- Formatting: Google C++ Style base, 100-column limit, 4-space indent. Let clang-format handle it.
	- Error handling: Use `Status` / `Result<T>` and project macros (`PAIMON_RETURN_NOT_OK`, `PAIMON_ASSIGN_OR_RAISE`). No exceptions.
	- Naming: PascalCase for classes and methods, snake_case for variables, trailing `_` for members.
	- Headers: `#pragma once`, includes ordered by category, Apache 2.0 license header on every file.
	- Factory pattern: Use `static Create()` + private constructor when construction can fail.
	- Testing: Google Test, `ASSERT_` preferred over `EXPECT_`, test files named `*_test.cpp` next to source.

	---

	## Dev Containers

	We provide Dev Container configuration file templates for VS Code:

	```bash
	cd .devcontainer
	cp Dockerfile.template Dockerfile
	cp devcontainer.json.template devcontainer.json
	```

	Then select Dev Containers: Reopen in Container from VS Code's Command Palette.

	If you make improvements that could benefit all developers, please update the template files and submit a pull request.

	---

	## License

	By contributing to Paimon C++, you agree that your contributions will be licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).