Skip to content

Commit b444455

Browse files
chernserchernser
authored
Merge pull request #2879 from ClickHouse/06/15/26/triage_issue_wf
[repo] Issue Triage WorkFlow
2 parents 6f25bcd + f1af93f commit b444455

4 files changed

Lines changed: 508 additions & 0 deletions

File tree

‎.cursor/skills/triage-issues/SKILL.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
name: triage-issues
3+
description: |
4+
Analyzes a single GitHub issue at a time. Reads the description, defines labels and priority, researches additional information, and provides a short but detailed report. Use when the user asks to triage an issue, analyze a bug report, or categorize a GitHub issue.
5+
disable-model-invocation: true
6+
---
7+
8+
# Issue Triage Workflow
9+
10+
## Stage 1: Preview
11+
12+
1. Sizes the description into categories: Tiny, Small, Medium, Large. See [Description Sizes in references.md](references.md) for size definitions.
13+
2. Analyzes based on description size:
14+
- **Tiny**: Tries to detect what module is affected. Uses specific terms and method names. JDBC, for example, has very recognizable sets of methods. Remembers or outputs additional information.
15+
- **Small or Medium**: Finds what module or functionality is affected and records this information. Small or Medium descriptions just need more technical details.
16+
- **Large**: Refines and compacts the issue for further investigation. Large descriptions should have enough data to pinpoint the problem but are often in a form hardly readable by humans, so creates a minimal version.
17+
3. Checks that there is minimal data available about the problem. See [Minimal Issue Details in references.md](references.md).
18+
19+
## Stage 2: Research
20+
21+
Before exploring the tree, use [source-map.md](source-map.md) to locate the
22+
affected module and `area:*` labels (module/package boundaries, label → source
23+
location, entry-point classes, and stacktrace → module heuristics). Only grep
24+
the source once the map has narrowed the scope.
25+
26+
Every issue type has its own research approach.
27+
28+
### Question
29+
30+
1. Looks up documentation first if there is related information. See [Module Documentation in references.md](references.md).
31+
2. If the question is about how configuration works - explores source code. See [Module Sources in references.md](references.md).
32+
3. If the question is about usage then generates a set of questions to get details about the use-case.
33+
4. Else, notes that this question needs human attention.
34+
35+
### Potential Bug
36+
37+
1. Finds out scope: determines the module, what configuration parameters are involved, and what classes implement the area.
38+
1. If there is a stacktrace, adds the call chain of methods for review.
39+
2. If there is a specific code example given, looks at what functions are called in what order.
40+
2. Understands the runtime environment more. Generates questions to discover more.
41+
1. If JDBC, then there could be some framework involved. Finds out what the conditions should be.
42+
2. If client, then the application environment is important.
43+
3. When the user provides a data example or use case description, creates a test scenario or code. Keeps code minimal.
44+
45+
### What to ask User
46+
47+
- Asks user about specific version of client or JDBC driver. Asks about specific version of server.
48+
- Asks about network setup if relevant. For example, issue related network may be affected by proxy in the middle.
49+
- Asks about reproducibility of the problem if it is network related and looks like have unstable nature.
50+
51+
## Stage 3: Summary
52+
53+
When finishing the analysis, outputs the findings using this exact template:
54+
~~~
55+
## Triage Report
56+
**Effort to Fix**: [Tiny/Small/Medium/Large]
57+
**Type**: [Question/Bug]
58+
**Affected Module**: [Module Name]
59+
### Summary
60+
[1-2 sentences summarizing the core issue]
61+
### Recommended Labels & Priority
62+
- Labels: [label1, label2]
63+
### Missing Information / Questions for User
64+
1. [Question 1]
65+
2. [Question 2]
66+
### Tests to Add
67+
68+
**Test 1: Scenario**
69+
```
70+
// code
71+
```
72+
73+
74+
**Test 2: Scenario**
75+
```
76+
// code
77+
```
78+
~~~

‎.cursor/skills/triage-issues/references.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Description Sizes
2+
3+
**Tiny**
4+
Problem is described in a few general words and mainly in issue title. For
5+
example, "getRow() throws exception", "client hangs", "Array serialization broken", etc.
6+
7+
**Small**
8+
Problem is described with minimal details but there is reference to a project
9+
or functionality. There can be a single stacktrace.
10+
11+
**Medium**
12+
Problem is described with enough details and tells what is broken and how
13+
it should work. There can be additional comments from author.
14+
15+
**Large**
16+
Problem is described with main details and examples. There is some explanation
17+
of the usecase. Sometimes there is a link to external demo project.
18+
19+
20+
# Minimal Issue Details
21+
22+
- Issue type: potential bug, feature request, chore
23+
- Affected component: language client or JDBC driver
24+
- Affected area: core functionality (data codecs, configuration validation, formats), special functionality (subset of core functionality or very specific feature) or general failure.
25+
26+
27+
# Module Documentation
28+
29+
External documentation (for human reference only — do NOT fetch these during
30+
automated triage; rely on the checked-out source under "Module Sources"):
31+
32+
- java client documentation: https://clickhouse.com/docs/integrations/language-clients/java/client
33+
- JDBC documentation: https://clickhouse.com/docs/integrations/language-clients/java/jdbc
34+
- JDBC working with date/time values: https://clickhouse.com/docs/integrations/language-clients/java/jdbc_date_time_guide
35+
36+
37+
# Module Sources
38+
39+
Local module directories in this checked-out repository (explore these with
40+
Read/Glob/Grep — do not follow external links):
41+
42+
- client v2: `client-v2/`
43+
- JDBC v2: `jdbc-v2/`
44+
- client v1: `clickhouse-http-client/` (also `clickhouse-client/`, `clickhouse-data/`)
45+
- JDBC v1: `clickhouse-jdbc/`
46+
47+
For a structural map (module/package boundaries, `area:*` label → source
48+
location, entry-point classes, and stacktrace → module heuristics) use
49+
[source-map.md](source-map.md). Consult it to locate the affected module/area
50+
before grepping the tree.
51+
52+
53+
# Labels
54+
55+
# Main
56+
57+
* **client-v1**: Use when issue is in old client version. Projects like `clickhouse-client`, `clickhouse-data`, etc.
58+
* **client-api-v2**: Use when issue is in the new client - `client-v2` project.
59+
* **jdbc-v1**: Use when issue is in the old JDBC driver - `clickhouse-jdbc` project.
60+
* **jdbc-v2**: Use when issue is in the new JDBC driver - `jdbc-v2` project.
61+
* **question**: Use when issue is asking question rather then describing a bug.
62+
* **investigating**: Use when more investigation is needed and it is not possible to pin point the problem.
63+
64+
# Area
65+
66+
* **`area:client-insert`**: Use when handling data insertion specifically in the ClickHouse client.
67+
* **`area:client-pojo-serde`**: Use for issues involving the Serialization and Deserialization (SerDe) of Plain Old Java Objects (POJOs).
68+
* **`area:client-read`**: Use when handling data reading specifically in the ClickHouse client.
69+
* **`area:data-type`**: Use for issues related to processing or handling different ClickHouse data types.
70+
* **`area:dependencies`**: Use for pull requests or issues that update, add, or remove a dependency file.
71+
* **`area:docs`**: Use when documentation is missing, incorrect, or needs updating.
72+
* **`area:error-handling`**: Use for tracking issues or improvements related to error and exception handling.
73+
* **`area:format`**: Use for issues handling specific data formats (e.g., JSON, CSV, RowBinary).
74+
* **`area:general`**: Use for general issues that do not neatly fit into any other specific `area:` category.
75+
* **`area:integration`**: Use for integration issues with third-party frameworks, tools, or systems.
76+
* **`area:jdbc-insert`**: Use for handling data insertion issues specifically related to the JDBC driver.
77+
* **`area:jdbc-metadata`**: Use for issues handling JDBC metadata, such as retrieving the type of a column or database properties.
78+
* **`area:jdbc-read`**: Use for reading data issues specifically related to the JDBC driver.
79+
* **`area:network`**: Use for tracking network configuration, connectivity, and I/O-related issues.
80+
* **`area:old-stmt-parsing`**: Use for issues concerning the parsing logic of older SQL statements.
81+
* **`area:packaging`**: Use for issues related to project packaging, builds, or distribution artifacts.
82+
* **`area:sql-parser`**: Use for issues, bugs, or feature requests regarding the custom SQL parser.

‎.cursor/skills/triage-issues/source-map.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Source Map
2+
3+
A structural map of the repository for fast, offline triage. Use it to pick the
4+
**module label** and **`area:*` labels** and to jump straight to the relevant
5+
source instead of grepping the whole tree.
6+
7+
Keep this map structural (modules, packages, entry points, label → location).
8+
Do not add line numbers or exhaustive class lists — they go stale. When a
9+
mapping below is wrong because the code moved, fix the boundary here.
10+
11+
## Modules at a glance
12+
13+
| Module label | Directory | Root package | What it is |
14+
| --- | --- | --- | --- |
15+
| `client-api-v2` | `client-v2/` | `com.clickhouse.client.api` | Current HTTP client (the "v2" client). |
16+
| `client-v1` | `clickhouse-client/`, `clickhouse-http-client/` | `com.clickhouse.client` (no `.api`) | Legacy v1 client stack. |
17+
| `client-v1` (data) | `clickhouse-data/` | `com.clickhouse.data` | Shared data types, codecs, formats, streams. Used by v1 and indirectly elsewhere. |
18+
| `jdbc-v2` | `jdbc-v2/` | `com.clickhouse.jdbc` | Current JDBC driver (built on client-v2). |
19+
| `jdbc-v1` | `clickhouse-jdbc/` | `com.clickhouse.jdbc` | Legacy JDBC driver (built on client-v1). |
20+
| (r2dbc) | `clickhouse-r2dbc/` | `com.clickhouse.r2dbc` | R2DBC integration. No dedicated label — use `area:integration`. |
21+
22+
23+
## Disambiguating v1 vs v2 (important)
24+
25+
Package prefixes overlap between versions, so use class-name cues:
26+
27+
- **Client v2 vs v1**: v2 lives under `com.clickhouse.client.api.*` and its entry
28+
point is `Client` (`client-v2/.../api/Client.java`). v1 lives under
29+
`com.clickhouse.client.*` / `com.clickhouse.client.http.*` with no `.api`
30+
segment (e.g. `ClickHouseClient`, `ClickHouseHttpClient`).
31+
- **JDBC v2 vs v1**: both use `com.clickhouse.jdbc`. v2 uses `*Impl` classes
32+
(`ConnectionImpl`, `StatementImpl`, `PreparedStatementImpl`, `ResultSetImpl`,
33+
`DatabaseMetaDataImpl`, `Driver`, `DataSourceImpl`) under `jdbc-v2/`.
34+
v1 uses `ClickHouse*` classes (`ClickHouseConnection`, `ClickHouseStatement`,
35+
`ClickHouseDriver`, `ClickHouseDataSource`) under `clickhouse-jdbc/`.
36+
- If the issue does not say which version, note it as a question for the user,
37+
but make a best guess from the class names / JDBC URL / Maven coordinates in
38+
the report.
39+
40+
41+
## `area:*` label → source location
42+
43+
Use these to attach `area:` labels and to find the implementing code.
44+
45+
- **`area:client-insert`** — `client-v2/.../api/insert/` (`InsertResponse`,
46+
`InsertSettings`) and `Client.insert*`. v1: `clickhouse-client`/`http-client`.
47+
- **`area:client-read`** — `client-v2/.../api/query/` (`QueryResponse`,
48+
`QuerySettings`, `GenericRecord`, `Records`) and `Client.query*`.
49+
- **`area:client-pojo-serde`** — `client-v2/.../api/serde/` (`POJOSerDe`,
50+
`POJOFieldSerializer`, `POJOFieldDeserializer`) and
51+
`client-v2/.../api/metadata/` matching strategies (`ColumnToMethodMatchingStrategy`).
52+
- **`area:data-type`** — `clickhouse-data/.../data/` core (`ClickHouseDataType`,
53+
`ClickHouseColumn`, `ClickHouseValue(s)`, `value/`) and client-v2
54+
`api/data_formats/` readers/writers. jdbc-v2 type wrappers in
55+
`jdbc-v2/.../jdbc/types/` (`Array`, `Struct`).
56+
- **`area:format`** — `clickhouse-data/.../data/format/` (RowBinary, TSV, JSON
57+
processors) and `client-v2/.../api/data_formats/` (`RowBinary*FormatReader/Writer`,
58+
`NativeFormatReader`). Compression: `clickhouse-data/.../data/compress/`.
59+
- **`area:network`** — `client-v2/.../api/transport/` (`Endpoint`, `HttpEndpoint`),
60+
`api/http/`, connection/config (`ClientConfigProperties`,
61+
`ConnectionInitiationException`, `ConnectionReuseStrategy`). v1:
62+
`clickhouse-http-client/.../client/http/`.
63+
- **`area:error-handling`** — exception types across modules: client-v2
64+
`ClientException`, `ServerException`, `ClickHouseException`, `ClientFaultCause`,
65+
`DataTransferException`; jdbc `SqlExceptionUtils` (v1); data `ClickHouseChecker`.
66+
- **`area:jdbc-insert`** — `jdbc-v2/.../jdbc/` `PreparedStatementImpl`,
67+
`WriterStatementImpl`. v1: `clickhouse-jdbc/.../jdbc/ClickHousePreparedStatement`.
68+
- **`area:jdbc-read`** — `jdbc-v2/.../jdbc/` `ResultSetImpl`, `StatementImpl`.
69+
v1: `ClickHouseResultSet`, `ClickHouseStatement`.
70+
- **`area:jdbc-metadata`** — `jdbc-v2/.../jdbc/metadata/` (`DatabaseMetaDataImpl`,
71+
`ResultSetMetaDataImpl`, `ParameterMetaDataImpl`). v1:
72+
`ClickHouseDatabaseMetaData`, `ClickHouseResultSetMetaData`, `JdbcTypeMapping`.
73+
- **`area:sql-parser`** — new parser in `jdbc-v2/.../jdbc/internal/parser/`
74+
(incl. `javacc/`).
75+
- **`area:old-stmt-parsing`** — legacy parser in
76+
`clickhouse-jdbc/.../jdbc/parser/` (`ClickHouseSqlParser`, `ClickHouseSqlUtils`,
77+
`ClickHouseSqlStatement`).
78+
- **`area:integration`** — `clickhouse-r2dbc/`, or third-party framework glue
79+
(Spring, Hibernate, etc.) referenced in the issue.
80+
- **`area:packaging`** — `packages/clickhouse-jdbc-all/`, Maven `pom.xml` build/
81+
shading/distribution concerns.
82+
- **`area:dependencies`** — dependency version bumps in `pom.xml` files.
83+
- **`area:docs`** — documentation gaps (no code area implied).
84+
- **`area:general`** — use only when nothing above fits.
85+
86+
87+
## Entry points (start reading here)
88+
89+
- **client-v2**: `client-v2/.../api/Client.java` (builder + query/insert API),
90+
`ClientConfigProperties` (config keys).
91+
- **jdbc-v2**: `jdbc-v2/.../jdbc/Driver.java`, `ConnectionImpl`, `StatementImpl`,
92+
`DriverProperties`.
93+
- **client-v1**: `clickhouse-client/.../client/` and
94+
`clickhouse-http-client/.../client/http/`.
95+
- **jdbc-v1**: `clickhouse-jdbc/.../jdbc/ClickHouseConnection.java`,
96+
`ClickHouseDriver`.
97+
- **data**: `clickhouse-data/.../data/ClickHouseDataProcessor`,
98+
`ClickHouseColumn`, `format/`.
99+
100+
101+
## Stacktrace → module heuristics
102+
103+
Map the top app-owned frames (ignore JDK/third-party frames) by package:
104+
105+
- `com.clickhouse.client.api.*` → **client-api-v2** (then pick area by sub-package:
106+
`insert`/`query`/`serde`/`data_formats`/`transport`).
107+
- `com.clickhouse.client.*` (no `.api`) / `com.clickhouse.client.http.*` →
108+
**client-v1**.
109+
- `com.clickhouse.jdbc.*Impl` or `com.clickhouse.jdbc.internal.parser.*` →
110+
**jdbc-v2**.
111+
- `com.clickhouse.jdbc.ClickHouse*` or `com.clickhouse.jdbc.parser.*` →
112+
**jdbc-v1**.
113+
- `com.clickhouse.data.*` → **clickhouse-data** (shared); attach `area:data-type`
114+
/ `area:format` / compression by sub-package. Identify the *caller* module to
115+
set the module label.
116+
- `com.clickhouse.r2dbc.*` → r2dbc (`area:integration`).

0 commit comments

Comments
 (0)