Skip to content

Re-style .proto files#7475

Merged
xzfc merged 4 commits intodevfrom
proto-style
Dec 16, 2025
Merged

Re-style .proto files#7475
xzfc merged 4 commits intodevfrom
proto-style

Conversation

@xzfc
Copy link
Member

@xzfc xzfc commented Oct 29, 2025

This PR improves the style of our .proto files. Commits in this PR:

1. doc comment style (automated)

Currenly, our .proto files use three different styles of comments: line comments on a separate line, multi-line block comments, and line comments at the end of a line. This snippet illustrates all three of them:

// Deprecated in favor of `max_optimization_threads`
optional uint64 deprecated_max_optimization_threads = 8;
/*
Max number of threads (jobs) for running optimizations per shard.
Note: each optimization job will also use `max_indexing_threads` threads by itself for index building.
If "auto" - have no limit and choose dynamically to saturate CPU.
If 0 - no optimization threads, optimizations will be disabled.
*/
optional MaxOptimizationThreads max_optimization_threads = 9;
}
message ScalarQuantization {
QuantizationType type = 1; // Type of quantization

The first commit in this PR converts all comments into a single style which is proposed by the Protobuf Language Guide:

Prefer C/C++/Java line-end-style comments ‘//’ on the line before the .proto code element

Conversion is done by running this script.
#!/usr/bin/env python3

import os
import re
import sys

RE_MULTILINE_COMMENT_START = re.compile(r"^( *)/\*\*?$")
RE_MULTILINE_COMMENT_END = re.compile(r"^ *\*/$")
RE_TRAILING_COMMENT = re.compile(r"^( *)([^ ].*;) +// (.*)$")

spaces = ""
in_comment = False
for fname in sys.argv[1:]:
    result = []
    with open(fname, "r") as file:
        for line in file:
            line = line.rstrip("\n")

            if m := RE_MULTILINE_COMMENT_START.match(line):
                assert not in_comment
                spaces = m[1]
                in_comment = True
            elif RE_MULTILINE_COMMENT_END.match(line):
                assert in_comment
                in_comment = False
            elif m := RE_TRAILING_COMMENT.match(line):
                assert not in_comment
                spaces, code, comment = m.groups()
                result.append(f"{spaces}// {comment}\n")
                result.append(f"{spaces}{code}\n")
            else:
                if in_comment:
                    line = line.lstrip()
                    result.append(f"{spaces}//{" " + line if line else ""}\n")
                else:
                    result.append(f"{line}\n")
    with open(fname + ".new", "w") as file:
        file.writelines(result)
    os.replace(fname + ".new", fname)

2. clang-format (automated)

The second commit runs clang-format to unify indenting/spaces. I believe that's the tool the company behind protobuf uses for their files.

clang-format \
	-style='{"BasedOnStyle": "Google", "ReflowComments": false}' \
	-i lib/api/src/grpc/proto/*.proto

While I like auto-reflow, it's too blunt for an automated mass-edit, so I disabled it and manually split some of the longer lines.

3. manually reflow some comments

See line above.

4. proofread

@xzfc xzfc requested review from generall and timvisee October 29, 2025 19:57
coderabbitai[bot]

This comment was marked as resolved.

@qdrant qdrant deleted a comment from coderabbitai bot Oct 30, 2025
@timvisee timvisee added release:1.16.0 Pull requests that should be merged for the Qdrant 1.16.0 release. do not merge Pull requests blocked on an external event and removed release:1.16.0 Pull requests that should be merged for the Qdrant 1.16.0 release. labels Oct 30, 2025
@timvisee
Copy link
Member

We agreed to merge this after the 1.16 release. That way we prevent this messing with proto diff's when updating clients. We can merge this after the release.

@xzfc xzfc removed the do not merge Pull requests blocked on an external event label Dec 16, 2025
@xzfc xzfc merged commit d093bd9 into dev Dec 16, 2025
15 checks passed
@xzfc xzfc deleted the proto-style branch December 16, 2025 22:22
@qdrant qdrant deleted a comment from coderabbitai bot Dec 17, 2025
timvisee pushed a commit that referenced this pull request Dec 18, 2025
* proto: doc comment style

* proto: clang-format

* proto: manually reflow some comments

* proto: proofread
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants