Skip to content

Commit afde921

Browse files
tsegismonttsegismont
authored
Instructions for coding agents (#1673)
* Instructions for coding agents This is an attempt to guide coding agents when contributing or reviewing code. AGENTS.md and SKILL.md are standards that should be understood by most coding agents. Signed-off-by: Thomas Segismont <tsegismont@gmail.com> * Improvements for testing Signed-off-by: Thomas Segismont <tsegismont@gmail.com> * Changes after review Signed-off-by: Thomas Segismont <tsegismont@gmail.com> --------- Signed-off-by: Thomas Segismont <tsegismont@gmail.com>
1 parent 5fc500e commit afde921

3 files changed

Lines changed: 351 additions & 0 deletions

File tree

‎.agents/skills/writing-tests/SKILL.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
name: writing-tests
3+
description: >
4+
Testing patterns for Vert.x SQL Client: test frameworks, async testing,
5+
test locations, and how to run tests.
6+
---
7+
8+
# Writing Tests
9+
10+
Vert.x SQL Client uses JUnit 4 with Vert.x-specific test utilities. Tests and documentation are mandatory for contributions.
11+
12+
## Test Framework
13+
14+
- **JUnit 4** (version 4.13.1) - Standard test framework
15+
- **VertxUnitRunner** - JUnit 4 runner for async tests
16+
- **TestContext** - Async test utility for handling asynchronous operations
17+
- **Docker** - Required for integration tests (database containers)
18+
19+
## Test Annotations and Extensions
20+
21+
### Standard Test Patterns
22+
23+
#### Pattern 1: Using Async with Simple Callback
24+
25+
```java
26+
@RunWith(VertxUnitRunner.class)
27+
public class MyTest {
28+
29+
@Test
30+
public void testWithAsync(TestContext ctx) {
31+
Async async = ctx.async();
32+
vertx.runOnContext(v -> async.complete());
33+
}
34+
}
35+
```
36+
37+
#### Pattern 2: Using asyncAssertSuccess Directly
38+
39+
When using `asyncAssertSuccess`, do not call `async.complete()` as it creates an async internally:
40+
41+
```java
42+
@RunWith(VertxUnitRunner.class)
43+
public class MyTest {
44+
45+
@Test
46+
public void testAsyncAssertSuccess(TestContext ctx) {
47+
client.query("SELECT 1")
48+
.execute()
49+
.onComplete(ctx.asyncAssertSuccess(result -> {
50+
ctx.assertEquals(1, result.size());
51+
}));
52+
}
53+
}
54+
```
55+
56+
#### Pattern 3: Using asyncAssertSuccess from runOnContext
57+
58+
When calling `asyncAssertSuccess` from `runOnContext`, you need an explicit async:
59+
60+
```java
61+
@RunWith(VertxUnitRunner.class)
62+
public class MyTest {
63+
64+
@Test
65+
public void testAsyncAssertSuccessFromRunOnContext(TestContext ctx) {
66+
Async async = ctx.async();
67+
vertx.runOnContext(v -> {
68+
client.query("SELECT 1")
69+
.execute()
70+
.onComplete(ctx.asyncAssertSuccess(result -> {
71+
ctx.assertEquals(1, result.size());
72+
async.complete();
73+
}));
74+
});
75+
}
76+
}
77+
```
78+
79+
## Test Location
80+
81+
- **Unit tests**: Same module as code under test, in `src/test/java/`
82+
- **Integration tests**: May be in separate test modules or `src/test/java/`
83+
- **Database-specific tests**: In respective client module
84+
- PostgreSQL: `vertx-pg-client/src/test/`
85+
- MySQL: `vertx-mysql-client/src/test/`
86+
- MSSQL: `vertx-mssql-client/src/test/`
87+
- DB2: `vertx-db2-client/src/test/`
88+
- Oracle: `vertx-oracle-client/src/test/`
89+
90+
## Test Data Setup
91+
92+
### Using SQL Scripts
93+
94+
Place initialization scripts in `src/test/resources/`:
95+
96+
```sql
97+
-- init.sql
98+
CREATE TABLE users (
99+
id SERIAL PRIMARY KEY,
100+
name VARCHAR(100) NOT NULL
101+
);
102+
103+
INSERT INTO users (name) VALUES ('Alice'), ('Bob');
104+
```
105+
106+
### Programmatic Setup
107+
108+
```java
109+
@Before
110+
public void setUp(TestContext ctx) {
111+
Async async = ctx.async();
112+
client.query("CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(100))")
113+
.execute()
114+
.compose(v -> client.query("INSERT INTO users (name) VALUES ('Alice'), ('Bob')").execute())
115+
.onComplete(ctx.asyncAssertSuccess(v -> async.complete()));
116+
}
117+
118+
@After
119+
public void tearDown(TestContext ctx) {
120+
Async async = ctx.async();
121+
client.query("DROP TABLE IF EXISTS users")
122+
.execute()
123+
.onComplete(ctx.asyncAssertSuccess(v -> async.complete()));
124+
}
125+
```
126+
127+
Prefer temporary tables when testing databases that support it (automatically dropped when the connection is closed).
128+
129+
## Test Requirements
130+
131+
- **All new features must include tests**
132+
- **Integration tests must clean up resources** (connections, containers)
133+
134+
## Assertions
135+
136+
### TestContext Assertions (JUnit 4 style)
137+
138+
```java
139+
ctx.assertEquals(expected, actual);
140+
ctx.assertTrue(condition);
141+
ctx.assertFalse(condition);
142+
ctx.assertNull(value);
143+
ctx.assertNotNull(value);
144+
```
145+
146+
## Common Pitfalls
147+
148+
1. **Forgetting to complete async tests** - Always call `async.complete()`

‎AGENTS.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Agent Guidelines - vertx-sql-client
2+
3+
Instructions for AI coding agents working in this repository.
4+
Checkout relevant `.agents/skills/` to accomplish specific tasks.
5+
6+
## Build & Verify Commands
7+
8+
```bash
9+
mvn test-compile # compile code and tests
10+
mvn test # run all tests (requires Docker for database interactions)
11+
mvn spotless:check # verify formatting
12+
mvn spotless:apply # auto-fix formatting
13+
```
14+
15+
## Project Structure
16+
17+
This is a multi-module Maven project with the following key modules:
18+
19+
- **vertx-sql-client**: Core SQL client API and base implementations
20+
- **vertx-sql-client-codec**: Shared codec utilities for data type encoding/decoding
21+
- **vertx-sql-client-templates**: SQL template support for type-safe queries
22+
- **vertx-pg-client**: PostgreSQL-specific client implementation
23+
- **vertx-mysql-client**: MySQL/MariaDB-specific client implementation
24+
- **vertx-mssql-client**: Microsoft SQL Server client implementation
25+
- **vertx-db2-client**: IBM DB2 client implementation
26+
- **vertx-oracle-client**: Oracle Database client implementation
27+
28+
### Module Layout Pattern
29+
30+
Each database-specific client follows this structure:
31+
- `src/main/java/`: Public API interfaces and implementation classes
32+
- Top package (e.g., `io.vertx.pgclient`): Public API interfaces
33+
- `impl/` subpackage: Implementation classes (not exported)
34+
- `src/main/asciidoc/`: Module-specific documentation
35+
- `src/test/java/`: Unit and integration tests
36+
- `module-info.java`: Defines module exports and dependencies
37+
38+
## General Coding Rules
39+
40+
These rules apply when **writing or modifying code**. Code review is the checkpoint where compliance is verified.
41+
42+
### Logging
43+
44+
In production code, use the Vert.x internal logger, never SLF4J, Log4j, or `java.util.logging` directly.
45+
46+
```java
47+
import io.vertx.core.internal.logging.Logger;
48+
import io.vertx.core.internal.logging.LoggerFactory;
49+
50+
private static final Logger logger = LoggerFactory.getLogger(MyClass.class);
51+
```
52+
53+
Vert.x internal logging API doesn't support parameters placeholders.
54+
Check the active level before debug or trace logging.
55+
56+
```java
57+
if (logger.isDebugEnabled()) {
58+
logger.debug("Prepared parameters: " + paramDesc);
59+
}
60+
```
61+
62+
### Async Patterns
63+
64+
Use Vert.x `Future<T>` and `Promise<T>` throughout. Do not use raw callbacks or `CompletableFuture` in production code.
65+
66+
### API Design
67+
68+
- Public contracts are interfaces in the top package (`io.vertx.sqlclient`, `io.vertx.pgclient`, …)
69+
- Implementations go in `impl/` subpackages
70+
- Annotate public API interfaces and methods with `@VertxGen` for code-generation support
71+
- Expose construction via static factory methods, not constructors
72+
73+
### Module Boundaries
74+
75+
`module-info.java` governs exports.
76+
Internal packages are exported only to their corresponding test modules, do not widen exports without discussion.
77+
Test module descriptors (`src/test/java/module-info.java`) can be modified freely, e.g. to add a `requires` for a new dependency used in tests.
78+
79+
### Copyright Header
80+
81+
New Java files must include the dual-license header matching existing files:
82+
83+
```java
84+
/*
85+
* Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
86+
*
87+
* This program and the accompanying materials are made available under the
88+
* terms of the Eclipse Public License 2.0 which is available at
89+
* http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
90+
* which is available at https://www.apache.org/licenses/LICENSE-2.0.
91+
*
92+
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
93+
*/
94+
```
95+
96+
The range is always `2011-[current year]`.
97+
98+
## Testing Guidelines
99+
100+
For comprehensive testing patterns and examples, see `.agents/skills/writing-tests/SKILL.md`.
101+
102+
### Test Framework
103+
104+
- Use **JUnit 4** (version 4.13.1) for all tests
105+
- Async tests use **VertxUnitRunner** (JUnit 4 runner) and **TestContext**
106+
- Integration tests require **Docker** for database containers
107+
108+
### Test Patterns
109+
110+
```java
111+
@RunWith(VertxUnitRunner.class)
112+
public class MyTest {
113+
114+
@Test
115+
public void testAsyncOperation(TestContext ctx) {
116+
Async async = ctx.async();
117+
client.query("SELECT 1")
118+
.execute()
119+
.onComplete(ctx.asyncAssertSuccess(result -> {
120+
ctx.assertEquals(1, result.size());
121+
async.complete();
122+
}));
123+
}
124+
}
125+
```
126+
127+
### Test Location
128+
129+
- **Unit tests**: Same module as code under test, in `src/test/java/`
130+
- **Integration tests**: May be in separate test modules or `src/test/java/`
131+
- **Database-specific tests**: In respective client module (e.g., `vertx-pg-client/src/test/`)
132+
133+
### Running Tests
134+
135+
```bash
136+
mvn test # Run all tests (requires Docker)
137+
mvn test -Dtest=MyTest # Run specific test class
138+
mvn test -Dtest=MyTest#testMethod # Run specific test method
139+
140+
# When your change spans modules (e.g. modifying vertx-sql-client-codec and
141+
# testing in vertx-pg-client), use -am to rebuild dependencies:
142+
mvn test -pl vertx-pg-client -am -Dtest=MyTest
143+
```
144+
145+
### Test Requirements
146+
147+
- All new features must include tests
148+
- Database tests must clean up resources (connections, containers)
149+
150+
## Development Workflow
151+
152+
### Incremental Development
153+
154+
When making changes:
155+
1. Compile frequently: `mvn compile -pl <module>`
156+
2. Run affected tests: `mvn test -pl <module>`
157+
3. Verify formatting: `mvn spotless:check`
158+
4. Run full build before PR: `mvn clean install`
159+
160+
### Build Optimization
161+
162+
```bash
163+
# Skip tests during development
164+
mvn compile -DskipTests
165+
166+
# Build specific module and dependencies
167+
mvn install -pl vertx-pg-client -am
168+
```
169+
170+
## Specialized Skills
171+
172+
When performing specific tasks, read the relevant skill file for detailed guidance:
173+
174+
- **Writing tests** - Read `.agents/skills/writing-tests/SKILL.md` when creating or modifying tests
175+
176+
## Contribution Process
177+
178+
- All commits must be signed off: `git commit -s` (DCO)
179+
- Commit messages should end with: `Assisted-by: [Provider] [Model-Family] ([Version/ID])` (replace placeholders)
180+
- Contributors must have signed the [Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php)
181+
182+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution workflow.
183+
184+
## Code Review Guidelines
185+
186+
### Verify
187+
188+
- General coding rules above are followed
189+
- Test coverage is present; async tests use `VertxUnitRunner` and `TestContext`
190+
- No breaking changes to public interfaces without prior discussion
191+
192+
### Do Not Comment On
193+
194+
- Patterns already used consistently throughout the codebase

‎CLAUDE.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
@AGENTS.md
2+
3+
# Agent Guidelines - vertx-sql-client
4+
5+
## Specialized Skills
6+
7+
When performing specific tasks, read the relevant skill file for detailed guidance:
8+
9+
- **Writing tests** - Read `.agents/skills/writing-tests/SKILL.md` when creating or modifying tests

0 commit comments

Comments
 (0)