Skip to content

Commit bb8841d

Browse files
tsegismonttsegismont
committed
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>
1 parent 5fc500e commit bb8841d

3 files changed

Lines changed: 307 additions & 0 deletions

File tree

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

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
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 Pattern
22+
23+
```java
24+
@RunWith(VertxUnitRunner.class)
25+
public class MyTest {
26+
27+
@Test
28+
public void testAsyncOperation(TestContext ctx) {
29+
Async async = ctx.async();
30+
client.query("SELECT 1")
31+
.execute()
32+
.onComplete(ctx.asyncAssertSuccess(result -> {
33+
ctx.assertEquals(1, result.size());
34+
async.complete();
35+
}));
36+
}
37+
}
38+
```
39+
40+
## Test Location
41+
42+
- **Unit tests**: Same module as code under test, in `src/test/java/`
43+
- **Integration tests**: May be in separate test modules or `src/test/java/`
44+
- **Database-specific tests**: In respective client module
45+
- PostgreSQL: `vertx-pg-client/src/test/`
46+
- MySQL: `vertx-mysql-client/src/test/`
47+
- MSSQL: `vertx-mssql-client/src/test/`
48+
- DB2: `vertx-db2-client/src/test/`
49+
- Oracle: `vertx-oracle-client/src/test/`
50+
51+
## Test Data Setup
52+
53+
### Using SQL Scripts
54+
55+
Place initialization scripts in `src/test/resources/`:
56+
57+
```sql
58+
-- init.sql
59+
CREATE TABLE users (
60+
id SERIAL PRIMARY KEY,
61+
name VARCHAR(100) NOT NULL
62+
);
63+
64+
INSERT INTO users (name) VALUES ('Alice'), ('Bob');
65+
```
66+
67+
### Programmatic Setup
68+
69+
```java
70+
@Before
71+
public void setUp(TestContext ctx) {
72+
Async async = ctx.async();
73+
client.query("CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(100))")
74+
.execute()
75+
.compose(v -> client.query("INSERT INTO users (name) VALUES ('Alice'), ('Bob')").execute())
76+
.onComplete(ctx.asyncAssertSuccess(v -> async.complete()));
77+
}
78+
79+
@After
80+
public void tearDown(TestContext ctx) {
81+
Async async = ctx.async();
82+
client.query("DROP TABLE IF EXISTS users")
83+
.execute()
84+
.onComplete(ctx.asyncAssertSuccess(v -> async.complete()));
85+
}
86+
```
87+
88+
Prefer temporary tables when testing databases that support it (automatically dropped when the connection is closed).
89+
90+
## Test Requirements
91+
92+
- **All new features must include tests**
93+
- **Integration tests must clean up resources** (connections, containers)
94+
95+
## Assertions
96+
97+
### TestContext Assertions (JUnit 4 style)
98+
99+
```java
100+
ctx.assertEquals(expected, actual);
101+
ctx.assertTrue(condition);
102+
ctx.assertFalse(condition);
103+
ctx.assertNull(value);
104+
ctx.assertNotNull(value);
105+
```
106+
107+
## Common Pitfalls
108+
109+
1. **Forgetting to complete async tests** - Always call `async.complete()`

‎AGENTS.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
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+
78+
### Copyright Header
79+
80+
New Java files must include the dual-license header matching existing files:
81+
82+
```java
83+
/*
84+
* Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
85+
*
86+
* This program and the accompanying materials are made available under the
87+
* terms of the Eclipse Public License 2.0 which is available at
88+
* http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
89+
* which is available at https://www.apache.org/licenses/LICENSE-2.0.
90+
*
91+
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
92+
*/
93+
```
94+
95+
The range is always `2011-[current year]`.
96+
97+
## Testing Guidelines
98+
99+
For comprehensive testing patterns and examples, see `.agents/skills/writing-tests/SKILL.md`.
100+
101+
### Test Framework
102+
103+
- Use **JUnit 4** (version 4.13.1) for all tests
104+
- Async tests use **VertxUnitRunner** (JUnit 4 runner) and **TestContext**
105+
- Integration tests require **Docker** for database containers
106+
107+
### Test Patterns
108+
109+
```java
110+
@RunWith(VertxUnitRunner.class)
111+
public class MyTest {
112+
113+
@Test
114+
public void testAsyncOperation(TestContext ctx) {
115+
Async async = ctx.async();
116+
client.query("SELECT 1")
117+
.execute()
118+
.onComplete(ctx.asyncAssertSuccess(result -> {
119+
ctx.assertEquals(1, result.size());
120+
async.complete();
121+
}));
122+
}
123+
}
124+
```
125+
126+
### Test Location
127+
128+
- **Unit tests**: Same module as code under test, in `src/test/java/`
129+
- **Integration tests**: May be in separate test modules or `src/test/java/`
130+
- **Database-specific tests**: In respective client module (e.g., `vertx-pg-client/src/test/`)
131+
132+
### Running Tests
133+
134+
```bash
135+
mvn test # Run all tests (requires Docker)
136+
mvn test -Dtest=MyTest # Run specific test class
137+
mvn test -Dtest=MyTest#testMethod # Run specific test method
138+
```
139+
140+
### Test Requirements
141+
142+
- All new features must include tests
143+
- Database tests must clean up resources (connections, containers)
144+
145+
## Development Workflow
146+
147+
### Incremental Development
148+
149+
When making changes:
150+
1. Compile frequently: `mvn compile -pl <module>`
151+
2. Run affected tests: `mvn test -pl <module>`
152+
3. Verify formatting: `mvn spotless:check`
153+
4. Run full build before PR: `mvn clean install`
154+
155+
### Build Optimization
156+
157+
```bash
158+
# Skip tests during development
159+
mvn compile -DskipTests
160+
161+
# Build specific module and dependencies
162+
mvn install -pl vertx-pg-client -am
163+
```
164+
165+
## Specialized Skills
166+
167+
When performing specific tasks, read the relevant skill file for detailed guidance:
168+
169+
- **Writing tests** - Read `.agents/skills/writing-tests/SKILL.md` when creating or modifying tests
170+
171+
## Contribution Process
172+
173+
- All commits must be signed off: `git commit -s` (DCO)
174+
- Commit messages should end with: `Assisted-by: [Provider] [Model-Family] ([Version/ID])` (replace placeholders)
175+
- Contributors must have signed the [Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php)
176+
177+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution workflow.
178+
179+
## Code Review Guidelines
180+
181+
### Verify
182+
183+
- General coding rules above are followed
184+
- Test coverage is present; async tests use `VertxUnitRunner` and `TestContext`
185+
- No breaking changes to public interfaces without prior discussion
186+
187+
### Do Not Comment On
188+
189+
- 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)