You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by "zhanghaou (via GitHub)" <gi...@apache.org> on 2026/03/10 02:59:19 UTC
[PR] [improve][CI] Add Copilot instructions based on Pulsar Java coding conventions [pulsar]
zhanghaou opened a new pull request, #25305:
URL: https://github.com/apache/pulsar/pull/25305
### Motivation
When using AI for code reviews, we can customize project-specific rules based on the Pulsar project to improve review quality and consistency. https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
This PR introduces `.github/copilot-instructions.md` based on the official [Pulsar Java coding conventions](https://pulsar.apache.org/contribute/develop-coding-conventions/).
The goal is to provide repository-specific context for AI-assisted code reviews (GitHub Copilot).
The instructions summarize the existing coding conventions, including formatting, logging, dependency usage, concurrency guidelines, and backward compatibility rules.
### Modifications
1、 Add review rules from coding conventions
2、Add Asynchronous Programming Guidelines
### Verifying this change
- [ ] Make sure that the change passes the CI checks.
*(Please pick either of the following options)*
This change is a trivial rework / code cleanup without any test coverage.
*(or)*
This change is already covered by existing tests, such as *(please describe tests)*.
*(or)*
This change added tests and can be verified as follows:
*(example:)*
- *Added integration tests for end-to-end deployment with large payloads (10MB)*
- *Extended integration test for recovery after broker failure*
### Does this pull request potentially affect one of the following parts:
<!-- DO NOT REMOVE THIS SECTION. CHECK THE PROPER BOX ONLY. -->
*If the box was checked, please highlight the changes*
- [ ] Dependencies (add or upgrade a dependency)
- [ ] The public API
- [ ] The schema
- [ ] The default values of configurations
- [ ] The threading model
- [ ] The binary protocol
- [ ] The REST endpoints
- [ ] The admin CLI options
- [ ] The metrics
- [ ] Anything that affects deployment
### Documentation
<!-- DO NOT REMOVE THIS SECTION. CHECK THE PROPER BOX ONLY. -->
- [ ] `doc` <!-- Your PR contains doc changes. -->
- [ ] `doc-required` <!-- Your PR changes impact docs and you will update later -->
- [x] `doc-not-needed` <!-- Your PR changes do not impact docs -->
- [ ] `doc-complete` <!-- Docs have been already added -->
### Matching PR in forked repository
PR in forked repository: <!-- ENTER URL HERE -->
<!--
After opening this PR, the build in apache/pulsar will fail and instructions will
be provided for opening a PR in the PR author's forked repository.
apache/pulsar pull requests should be first tested in your own fork since the
apache/pulsar CI based on GitHub Actions has constrained resources and quota.
GitHub Actions provides separate quota for pull requests that are executed in
a forked repository.
The tests will be run in the forked repository until all PR review comments have
been handled, the tests pass and the PR is approved by a reviewer.
-->
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [improve][CI] Add Copilot instructions based on Pulsar Java coding conventions [pulsar]
Posted by "zhanghaou (via GitHub)" <gi...@apache.org>.
zhanghaou commented on PR #25305:
URL: https://github.com/apache/pulsar/pull/25305#issuecomment-4030693602
@lhotari Thanks for the review. Addressed all comments.
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [improve][CI] Add Copilot instructions based on Pulsar Java coding conventions [pulsar]
Posted by "lhotari (via GitHub)" <gi...@apache.org>.
lhotari merged PR #25305:
URL: https://github.com/apache/pulsar/pull/25305
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [improve][CI] Add Copilot instructions based on Pulsar Java coding conventions [pulsar]
Posted by "lhotari (via GitHub)" <gi...@apache.org>.
lhotari commented on code in PR #25305:
URL: https://github.com/apache/pulsar/pull/25305#discussion_r2910552102
##########
.github/copilot-instructions.md:
##########
@@ -0,0 +1,266 @@
+The following instructions are only to be applied when performing a code review.
+
+# Copilot Instructions for Apache Pulsar
+
+## Project Context
+
+Apache Pulsar is a distributed messaging and streaming platform designed for high throughput, low latency, and
+horizontal scalability.
+
+The codebase contains performance-critical, asynchronous, and concurrency-sensitive components such as brokers, storage
+clients, and networking layers.
+
+Code reviews should prioritize:
+
+* correctness
+* thread safety
+* performance
+* maintainability
+* backward compatibility
+
+---
+
+# Java Coding Conventions
+
+Apache Pulsar follows the Sun Java Coding Conventions with additional project-specific rules.
+
+## Formatting
+
+* Use **4 spaces** for indentation.
+* **Tabs must never be used**.
+* Always use **curly braces**, even for single-line `if` statements.
+
+Example:
+
+```java
+if (condition) {
+ doSomething();
+}
+```
+
+## Javadoc
+
+* Do **not include `@author` tags** in Javadoc.
+
+## TODO Comments
+
+All TODO comments must reference a GitHub issue.
+
+Example:
+
+```java
+// TODO: https://github.com/apache/pulsar/issues/XXXX
+```
+
+---
+
+# Dependencies
+
+Prefer existing dependencies instead of introducing new libraries.
+
+The Pulsar codebase commonly uses:
+
+* **Guava** for utilities
+* **Netty** for networking and buffers
+
+When introducing a new dependency:
+
+* justify why existing dependencies are insufficient
+* ensure required license files and notices are updated
+
+---
+
+# Logging Guidelines
+
+* Use **SLF4J** for logging.
+* Do **not use** `System.out` or `System.err`.
+* Assume production commonly runs at **INFO** log level.
+* Avoid excessive logging in hot paths.
+* Guard expensive `DEBUG` and `TRACE` logging with `log.isDebugEnabled()` or `log.isTraceEnabled()`.
+* Avoid logging stack traces at `INFO` and lower levels.
+
+Log messages should be:
+
+* clear and descriptive
+* capitalized
+* understandable without reading the code
+
+---
+
+# Resource and Memory Management
+
+Ensure resources are always closed correctly.
+
+Prefer:
+
+```java
+try (InputStream in = ...) {
+ // use resource
+}
+```
+
+Avoid leaks for:
+
+* streams
+* network connections
+* executors
+* buffers
+
+For internal networking/messaging paths, prefer **Netty `ByteBuf`** over `ByteBuffer` unless an external API requires
+`ByteBuffer`.
+
+---
+
+# Configuration Guidelines
+
+When adding configuration options:
+
+* use clear and descriptive names
+* provide sensible default values
+* update default configuration files
+* document the configuration option
+
+---
+
+# Concurrency Guidelines
+
+Pulsar is designed as a low-latency asynchronous system.
+
+Verify:
+
+* public classes are **thread-safe**
+* shared mutable state is protected
+* mutations occur on the intended thread
+* fine-grained synchronization is preferred
+* threads have meaningful names for diagnostics
+
+If a class is not thread-safe, annotate it with:
+
+```java
+@NotThreadSafe
+```
+
+Prefer **OrderedExecutor** for ordered asynchronous execution.
+
+---
+
+# Asynchronous Programming Guidelines
+
+Pulsar relies heavily on `CompletableFuture` and asynchronous pipelines.
+
+Prefer `CompletableFuture` APIs over `ListenableFuture` for new code.
+
+## Avoid Blocking in Async Paths
+
+Do not introduce blocking operations in asynchronous execution paths.
+
+Examples of blocking operations:
+
+* `Thread.sleep`
+* `Future.get()`
+* `CompletableFuture.join()`
+* blocking IO operations
+
+Blocking calls must not run on event loop or async execution threads.
+
+## Avoid Nested Futures
+
+Avoid returning nested futures such as:
+
+```java
+CompletableFuture<CompletableFuture<T>>
+```
+
+Prefer flattening with `thenCompose`.
+
+## Asynchronous Exception Handling
+
+Methods returning `CompletableFuture` must not throw synchronous exceptions directly.
+
+Incorrect:
+
+```java
+public CompletableFuture<Void> operation() {
+ if (error) {
+ throw new IllegalStateException("unexpected state");
+ }
+ return CompletableFuture.completedFuture(null);
+}
+```
+
+Use returned futures to propagate failures:
+
+```java
+return CompletableFuture.failedFuture(exception);
+```
+
+This also applies to argument validation in async methods:
+
+```java
+if (arg == null) {
+ return CompletableFuture.failedFuture(new IllegalArgumentException("arg"));
+}
+```
+
+Throwing exceptions inside async stages such as `thenApply`, `thenCompose`, `thenRun`, `handle`, or `whenComplete`
+is acceptable:
+
+```java
+return future.thenApply(v -> {
+ if (error) {
+ throw new IllegalStateException("unexpected state");
+ }
+ return result;
+});
+```
+
+---
+
+# Backward Compatibility
+
+Apache Pulsar maintains strong compatibility guarantees.
+
+Changes must not break:
+
+* public APIs
+* client compatibility
+* wire protocol compatibility
+* metadata or serialized formats
+
+Servers must be compatible with both older and newer clients.
+
+Flag any change that may break compatibility.
+
+---
+
+# Testing Expectations
Review Comment:
```suggestion
# Testing guidelines
## Unit testing
* TestNG is used as the testing framework
* Mocking uses Mockito
* Assertions should prefer using AssertJ library with descriptions over using TestNG assertions
* Awaitility should be used to handle assertions with asynchronous conditions together with AssertJ
## Testing Expectations
```
##########
.github/copilot-instructions.md:
##########
@@ -0,0 +1,266 @@
+The following instructions are only to be applied when performing a code review.
+
+# Copilot Instructions for Apache Pulsar
+
+## Project Context
+
+Apache Pulsar is a distributed messaging and streaming platform designed for high throughput, low latency, and
+horizontal scalability.
+
+The codebase contains performance-critical, asynchronous, and concurrency-sensitive components such as brokers, storage
+clients, and networking layers.
+
+Code reviews should prioritize:
+
+* correctness
+* thread safety
+* performance
+* maintainability
+* backward compatibility
+
+---
+
+# Java Coding Conventions
+
+Apache Pulsar follows the Sun Java Coding Conventions with additional project-specific rules.
+
+## Formatting
+
+* Use **4 spaces** for indentation.
+* **Tabs must never be used**.
+* Always use **curly braces**, even for single-line `if` statements.
+
+Example:
+
+```java
+if (condition) {
+ doSomething();
+}
+```
+
+## Javadoc
+
+* Do **not include `@author` tags** in Javadoc.
+
+## TODO Comments
+
+All TODO comments must reference a GitHub issue.
+
+Example:
+
+```java
+// TODO: https://github.com/apache/pulsar/issues/XXXX
+```
+
+---
+
+# Dependencies
+
+Prefer existing dependencies instead of introducing new libraries.
+
+The Pulsar codebase commonly uses:
+
+* **Guava** for utilities
Review Comment:
Add more
```suggestion
* **Apache Commons** libraries for utilities
* **Guava** for utilities
* **Fastutil** for optimized type specific collections
* **JCTools** for high performance concurrent datastructures
* **RoaringBitmap** for compressed bitmaps (bitsets)
* **Caffeine** for caching
* **Jackson** for JSON handling
* **Prometheus Java simpleclient** (or newer **Prometheus Java Metrics Library**) for metrics
* **OpenTelemetry API** for metrics
```
##########
.github/copilot-instructions.md:
##########
@@ -0,0 +1,266 @@
+The following instructions are only to be applied when performing a code review.
+
+# Copilot Instructions for Apache Pulsar
+
+## Project Context
+
+Apache Pulsar is a distributed messaging and streaming platform designed for high throughput, low latency, and
+horizontal scalability.
+
+The codebase contains performance-critical, asynchronous, and concurrency-sensitive components such as brokers, storage
+clients, and networking layers.
+
+Code reviews should prioritize:
+
+* correctness
+* thread safety
+* performance
+* maintainability
+* backward compatibility
+
+---
+
+# Java Coding Conventions
+
+Apache Pulsar follows the Sun Java Coding Conventions with additional project-specific rules.
+
+## Formatting
+
+* Use **4 spaces** for indentation.
+* **Tabs must never be used**.
+* Always use **curly braces**, even for single-line `if` statements.
+
+Example:
+
+```java
+if (condition) {
+ doSomething();
+}
+```
+
+## Javadoc
+
+* Do **not include `@author` tags** in Javadoc.
+
+## TODO Comments
+
+All TODO comments must reference a GitHub issue.
+
+Example:
+
+```java
+// TODO: https://github.com/apache/pulsar/issues/XXXX
+```
+
+---
+
+# Dependencies
+
+Prefer existing dependencies instead of introducing new libraries.
+
+The Pulsar codebase commonly uses:
+
+* **Guava** for utilities
+* **Netty** for networking and buffers
+
+When introducing a new dependency:
+
+* justify why existing dependencies are insufficient
+* ensure required license files and notices are updated
+
+---
+
+# Logging Guidelines
+
+* Use **SLF4J** for logging.
+* Do **not use** `System.out` or `System.err`.
+* Assume production commonly runs at **INFO** log level.
+* Avoid excessive logging in hot paths.
+* Guard expensive `DEBUG` and `TRACE` logging with `log.isDebugEnabled()` or `log.isTraceEnabled()`.
+* Avoid logging stack traces at `INFO` and lower levels.
+
+Log messages should be:
+
+* clear and descriptive
+* capitalized
+* understandable without reading the code
+
+---
+
+# Resource and Memory Management
+
+Ensure resources are always closed correctly.
+
+Prefer:
+
+```java
+try (InputStream in = ...) {
+ // use resource
+}
+```
+
+Avoid leaks for:
+
+* streams
+* network connections
+* executors
+* buffers
+
+For internal networking/messaging paths, prefer **Netty `ByteBuf`** over `ByteBuffer` unless an external API requires
+`ByteBuffer`.
+
+---
+
Review Comment:
```suggestion
---
# Metrics Guidelines
New metrics should be made available with both Prometheus simpleclient (or newer Prometheus client_java) and OpenTelemetry API.
---
```
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [improve][CI] Add Copilot instructions based on Pulsar Java coding conventions [pulsar]
Posted by "zhanghaou (via GitHub)" <gi...@apache.org>.
zhanghaou commented on PR #25305:
URL: https://github.com/apache/pulsar/pull/25305#issuecomment-4028312642
It can highlight issues like this.
<img width="768" height="475" alt="image" src="https://github.com/user-attachments/assets/d2d2fafe-ae8c-4d8a-abea-c6cc4a128bcf" />
https://github.com/zhanghaou/pulsar/pull/4
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org