Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 47 additions & 28 deletions .gemini/styleguide.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,34 @@

## Introduction

This document defines the coding standards for C++ code in ZKIR.
The base guideline is the [LLVM Coding Standard], combined with the [Angular Commit Convention], with explicit project-specific modifications.
In addition to code style, this guide incorporates our rules for commit messages, pull requests, and IDE/editor setup.
This document defines the coding standards for C++ code in ZKIR. The base
guideline is the [LLVM Coding Standard], combined with the
[Angular Commit Convention], with explicit project-specific modifications. In
addition to code style, this guide incorporates our rules for commit messages,
pull requests, and IDE/editor setup.

---
______________________________________________________________________

## Core Principles

- **Readability:** Both code and commits should be immediately understandable.
- **Maintainability:** Code should be easy to refactor and extend.
- **Consistency:** Apply the same conventions across files and modules, except where external code (e.g., XLA) is imported.
- **Performance:** Prioritize clarity, but optimize carefully where latency and cost are critical.
- **Consistency:** Apply the same conventions across files and modules, except
where external code (e.g., XLA) is imported.
- **Performance:** Prioritize clarity, but optimize carefully where latency and
cost are critical.

---
______________________________________________________________________

## C++ Coding Style

The following are project-specific deviations and clarifications from the [LLVM Coding Standard].
The following are project-specific deviations and clarifications from the
[LLVM Coding Standard].

### Static Methods

- For **static methods** implemented in `.cc` files, explicitly annotate with `// static`.
- For **static methods** implemented in `.cc` files, explicitly annotate with
`// static`.

```c++
// static
Expand All @@ -34,7 +40,8 @@ The following are project-specific deviations and clarifications from the [LLVM

### File-Scoped Symbols

- Wrap **file-scoped functions, constants, and variables** inside an **anonymous namespace**.
- Wrap **file-scoped functions, constants, and variables** inside an **anonymous
namespace**.

```c++
namespace {
Expand All @@ -54,7 +61,8 @@ The following are project-specific deviations and clarifications from the [LLVM

### Header Inclusion

- **Avoid redundant includes**: Do not repeat headers in `.cc` files that are already included in the corresponding `.h`.
- **Avoid redundant includes**: Do not repeat headers in `.cc` files that are
already included in the corresponding `.h`.

```c++
// in a.h
Expand All @@ -69,7 +77,8 @@ The following are project-specific deviations and clarifications from the [LLVM

### Raw Pointer Ownership

- When using a **raw pointer** (`T*`) in **class or struct members**, explicitly document ownership by adding an inline comment `// not owned` or `// owned`.
- When using a **raw pointer** (`T*`) in **class or struct members**, explicitly
document ownership by adding an inline comment `// not owned` or `// owned`.
- Prefer `std::unique_ptr` or `std::shared_ptr` for owned resources.

Example:
Expand All @@ -85,48 +94,57 @@ class Prover {
};
```

---
______________________________________________________________________

## Comment Style

- Non-trivial code changes must be accompanied by comments.
- Comments should explain **why** a change or design decision was made, not just what the code does.
- Comments should explain **why** a change or design decision was made, not just
what the code does.
- Use full sentences with proper punctuation.

---
______________________________________________________________________

## Bazel Style

- Every header included in a Bazel target must also be declared as a Bazel dependency.
- Every header included in a Bazel target must also be declared as a Bazel
dependency.

---
______________________________________________________________________

## Testing

- **Framework**: Use gtest/gmock.
- **Coverage**: New features must include tests whenever applicable.
- **Completeness**: Always include boundary cases and error paths.
- **Determinism**: Tests must be deterministic and runnable independently (no hidden state dependencies).
- **Performance**: Add benchmarks for performance-critical code paths when appropriate.
- **Determinism**: Tests must be deterministic and runnable independently (no
hidden state dependencies).
- **Performance**: Add benchmarks for performance-critical code paths when
appropriate.

---
______________________________________________________________________

## Collaboration Rules

### Commits (Angular Commit Convention)

- Must follow the [Commit Message Guideline].

- Format:

```
<type>(<scope>): <summary>
```

where `type` ∈ {build, chore, ci, docs, feat, fix, perf, refactor, style, test}.
where `type` ∈ {build, chore, ci, docs, feat, fix, perf, refactor, style,
test}.

- Commit body: explain **why** the change was made (minimum 20 characters).

- Footer: record breaking changes, deprecations, and related issues/PRs.
- Each commit must include only **minimal, logically related changes**. Avoid mixing style fixes with functional changes.

- Each commit must include only **minimal, logically related changes**. Avoid
mixing style fixes with functional changes.

### Pull Requests

Expand All @@ -140,17 +158,18 @@ class Prover {
- No trailing whitespace.
- No extra blank lines at EOF.

---
______________________________________________________________________

## Tooling

- **Formatter:** `clang-format` (LLVM preset with project overrides). Refer to the [.clang-format] file in the repo.
- **Formatter:** `clang-format` (LLVM preset with project overrides). Refer to
the [.clang-format] file in the repo.
- **Linter:** `clang-tidy`.
- **Pre-commit hooks:** Recommended for enforcing format and lint locally.
- **CI:** All PRs must pass lint, format, and tests before merge.

[LLVM Coding Standard]: https://llvm.org/docs/CodingStandards.html
[Angular Commit Convention]: https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md
[Commit Message Guideline]: https://github.com/zk-rabbit/.github/blob/main/COMMIT_MESSAGE_GUIDELINE.md
[Pull Request Guideline]: https://github.com/zk-rabbit/.github/blob/main/PULL_REQUEST_GUIDELINE.md
[.clang-format]: /.clang-format
[angular commit convention]: https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md
[commit message guideline]: https://github.com/zk-rabbit/.github/blob/main/COMMIT_MESSAGE_GUIDELINE.md
[llvm coding standard]: https://llvm.org/docs/CodingStandards.html
[pull request guideline]: https://github.com/zk-rabbit/.github/blob/main/PULL_REQUEST_GUIDELINE.md
7 changes: 4 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,10 @@ jobs:
- name: Install cpplint
run: pip install cpplint

- name: Refresh compile commands
run: |
bazel run --remote_cache=grpc://127.0.0.1:9092 @hedron_compile_commands//:refresh_all
# FIXME(ashjeong): clang-tidy currently fails on CI. See https://github.com/zk-rabbit/zkir/actions/runs/16904324348/job/47890440254 for more details.
# - name: Refresh compile commands
# run: |
# bazel run --remote_cache=grpc://127.0.0.1:9092 @hedron_compile_commands//:refresh_all

- name: Run pre-commit github action
uses: pre-commit/action@646c83fcd040023954eafda54b4db0192ce70507 # pin@v3
24 changes: 12 additions & 12 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -21,19 +21,19 @@ repos:
"--filter=-whitespace/indent_namespace, -legal/copyright, -build/namespaces, -runtime/references",
]

# clang-tidy
# FIXME(ashjeong): clang-tidy currently fails on CI. See https://github.com/zk-rabbit/zkir/actions/runs/16904324348/job/47890440254 for more details.
# This hook now relies on a local shell script.
- repo: local
hooks:
- id: clang-tidy
name: clang-tidy
entry: ./run_clang_tidy.sh
language: script
files: '\.(c|cc|cpp|cxx|h|hh|hpp|hxx)$'
exclude: |
(?x)
(^|/)(bazel-.*|bazel-out/|build/|out/|third_party/|external/)
pass_filenames: true
# - repo: local
# hooks:
# - id: clang-tidy
# name: clang-tidy
# entry: ./run_clang_tidy.sh
# language: script
# files: '\.(c|cc|cpp|cxx|h|hh|hpp|hxx)$'
# exclude: |
# (?x)
# (^|/)(bazel-.*|bazel-out/|build/|out/|third_party/|external/)
# pass_filenames: true

# clang-format
- repo: https://github.com/pre-commit/mirrors-clang-format
Expand Down