Skip to content

Commit 744c686

Browse files
magnuspmagnusp
committed
chore: setup open source community files, workflows, and guidelines
1 parent fc7f4f9 commit 744c686

26 files changed

Lines changed: 861 additions & 22 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Bug Report
2+
description: File a bug report to help us improve libsql-java
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for taking the time to fill out this bug report!
10+
- type: textarea
11+
id: description
12+
attributes:
13+
label: Bug Description
14+
description: A clear and concise description of what the bug is.
15+
validations:
16+
required: true
17+
- type: textarea
18+
id: reproduction
19+
attributes:
20+
label: Steps to Reproduce
21+
description: Steps or minimal code snippet to reproduce the behavior.
22+
placeholder: |
23+
1. Connect with url 'jdbc:libsql:...'
24+
2. Execute query '...'
25+
3. See error
26+
validations:
27+
required: true
28+
- type: textarea
29+
id: expected
30+
attributes:
31+
label: Expected Behavior
32+
description: A clear and concise description of what you expected to happen.
33+
validations:
34+
required: true
35+
- type: input
36+
id: environment
37+
attributes:
38+
label: Environment
39+
description: JDK version, OS, sqld version, etc.
40+
placeholder: "e.g. Amazon Corretto 26, Linux x86_64, sqld 0.24"
41+
validations:
42+
required: false
43+
- type: textarea
44+
id: additional-context
45+
attributes:
46+
label: Additional Context
47+
description: Add any other context, stack traces, or logs here.
48+
validations:
49+
required: false

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Feature Request
2+
description: Suggest an idea or enhancement for libsql-java
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for suggesting a new feature or improvement!
10+
- type: textarea
11+
id: problem
12+
attributes:
13+
label: Problem Description
14+
description: Is your feature request related to a problem or missing capability?
15+
placeholder: "I'm always frustrated when..."
16+
validations:
17+
required: true
18+
- type: textarea
19+
id: solution
20+
attributes:
21+
label: Proposed Solution
22+
description: Describe the solution or feature you'd like to see.
23+
validations:
24+
required: true
25+
- type: textarea
26+
id: alternatives
27+
attributes:
28+
label: Alternatives Considered
29+
description: Describe any alternative solutions or features you've considered.
30+
validations:
31+
required: false
32+
- type: textarea
33+
id: additional-context
34+
attributes:
35+
label: Additional Context
36+
description: Add any other context, API design sketches, or references here.
37+
validations:
38+
required: false

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Description
2+
3+
Please provide a summary of the change and which issue it fixes or relates to. Include relevant motivation and context.
4+
5+
Fixes #(issue)
6+
7+
## Type of Change
8+
9+
- [ ] Bug fix (non-breaking change fixing an issue)
10+
- [ ] New feature (non-breaking change adding functionality)
11+
- [ ] Breaking change (fix or feature causing existing functionality to not work as expected)
12+
- [ ] Documentation update
13+
- [ ] Refactoring / tooling / CI improvement
14+
15+
## Checklist
16+
17+
- [ ] My code follows the code style of this project (`./mvnw spotless:check`).
18+
- [ ] I have added tests that prove my fix is effective or that my feature works.
19+
- [ ] All new and existing tests passed (`./mvnw clean verify`).
20+
- [ ] I have updated documentation where appropriate.

‎.github/dependabot.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "maven"
4+
directory: "/"
5+
schedule:
6+
interval: "weekly"
7+
open-pull-requests-limit: 10
8+
labels:
9+
- "dependencies"
10+
11+
- package-ecosystem: "github-actions"
12+
directory: "/"
13+
schedule:
14+
interval: "weekly"
15+
open-pull-requests-limit: 10
16+
labels:
17+
- "dependencies"
18+
- "github-actions"

‎.github/workflows/ci.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: CI & Integration Tests
2+
3+
on:
4+
push:
5+
branches: [ "main" ]
6+
pull_request:
7+
branches: [ "main" ]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
build-and-test:
14+
name: Build & Test (Java ${{ matrix.java-version }})
15+
runs-on: ubuntu-latest
16+
strategy:
17+
fail-fast: false
18+
matrix:
19+
java-version: ['25', '26']
20+
steps:
21+
- name: Checkout code
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Amazon Corretto ${{ matrix.java-version }}
25+
uses: actions/setup-java@v4
26+
with:
27+
distribution: 'corretto'
28+
java-version: ${{ matrix.java-version }}
29+
cache: 'maven'
30+
31+
- name: Check Code Formatting (Spotless)
32+
run: mvn --batch-mode spotless:check
33+
34+
- name: Run Tests and Verifications
35+
run: mvn --batch-mode clean verify

‎.github/workflows/codeql.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: "CodeQL Advanced Security Analysis"
2+
3+
on:
4+
push:
5+
branches: [ "main" ]
6+
pull_request:
7+
branches: [ "main" ]
8+
schedule:
9+
- cron: '0 6 * * 1' # Every Monday at 06:00 UTC
10+
11+
permissions:
12+
contents: read
13+
security-events: write
14+
15+
jobs:
16+
analyze:
17+
name: Analyze Code with CodeQL
18+
runs-on: ubuntu-latest
19+
timeout-minutes: 360
20+
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@v4
24+
25+
- name: Set up Java LTS (Corretto 25)
26+
uses: actions/setup-java@v4
27+
with:
28+
distribution: 'corretto'
29+
java-version: '25'
30+
cache: 'maven'
31+
32+
- name: Initialize CodeQL
33+
uses: github/codeql-action/init@v3
34+
with:
35+
languages: 'java-kotlin'
36+
build-mode: 'autobuild'
37+
38+
- name: Perform CodeQL Analysis
39+
uses: github/codeql-action/analyze@v3
40+
with:
41+
category: "/language:java-kotlin"

‎.github/workflows/publish.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Publish to GitHub Packages
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
permissions:
9+
contents: read
10+
packages: write
11+
id-token: write # Required for generating build provenance and cryptographic attestation
12+
attestations: write
13+
14+
jobs:
15+
publish:
16+
name: Build, Attest & Publish
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout code
20+
uses: actions/checkout@v4
21+
22+
- name: Set up Amazon Corretto 25
23+
uses: actions/setup-java@v4
24+
with:
25+
distribution: 'corretto'
26+
java-version: '25'
27+
cache: 'maven'
28+
29+
- name: Build & Publish to GitHub Packages
30+
env:
31+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
32+
run: |
33+
RELEASE_VERSION="${GITHUB_REF_NAME#v}"
34+
echo "Publishing release version ${RELEASE_VERSION}"
35+
mvn --batch-mode clean deploy \
36+
-Prelease \
37+
-Drevision="${RELEASE_VERSION}" \
38+
-DskipTests \
39+
-DaltDeploymentRepository=github::https://maven.pkg.github.com/${{ github.repository }}
40+
41+
- name: Generate Artifact Attestation (Provenance)
42+
uses: actions/attest-build-provenance@v2
43+
with:
44+
subject-path: '**/target/*.jar'

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@ target/
55
.vscode/
66
.DS_Store
77
*.log
8+
.flattened-pom.xml

‎AGENTS.md‎

Lines changed: 94 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,95 @@
1-
# Tools
1+
# Contributor & Agent Guidelines
22

3-
We target Java 26 LTS. Tools are installed with mise
3+
Welcome to `libsql-java`. This repository implements a pure-Java JDBC driver, client library, and protocol codec for libSQL / sqld over the Hrana protocol.
4+
5+
This guide provides developers and automated AI agents with instructions on architecture, tooling, build conventions, and verification workflows.
6+
7+
---
8+
9+
## 1. Environment & Tooling Prerequisites
10+
11+
- **Java Version**: Java LTS.
12+
- **Environment Management**: Tooling is managed via [mise](https://mise.jdx.dev/) (`mise.toml`).
13+
- **Build System**: Maven with the included wrapper (`./mvnw`).
14+
- **Container Runtime**: Docker or Podman (with socket exposed) for Testcontainers.
15+
16+
### Setup Commands
17+
```bash
18+
# Ensure correct Java LTS environment
19+
mise install
20+
21+
# Verify Java & Maven
22+
mise exec -- java -version
23+
mise exec -- ./mvnw -version
24+
```
25+
26+
---
27+
28+
## 2. Architecture & Module Structure
29+
30+
```text
31+
libsql-java/
32+
├── libsql-hrana-codec/ # Core protocol data structures & DirectHranaJsonCodec
33+
├── libsql-client/ # Low-level HTTP transport, baton state management, pipeline queue
34+
├── libsql-jdbc/ # Standard JDBC 4.3 driver (java.sql.* implementation)
35+
├── libsql-itests/ # Testcontainers (sqld) and Toxiproxy integration tests
36+
└── vendor/ # Upstream specifications and documentation (Hrana v3, sqld)
37+
```
38+
39+
### Module Guidelines
40+
1. **`libsql-hrana-codec`**:
41+
- Zero external runtime dependencies.
42+
- `DirectHranaJsonCodec` handles streaming JSON encoding/decoding directly for maximum performance.
43+
- Preserves 64-bit integer precision and binary base64 encoding.
44+
45+
2. **`libsql-client`**:
46+
- Built on `java.net.http.HttpClient` with pooled connection reuse.
47+
- Manages baton lifecycle, `/v3/pipeline` execution, and stream close handshakes.
48+
49+
3. **`libsql-jdbc`**:
50+
- Standards-compliant JDBC 4.3 implementation.
51+
- Maps URL schemes: `jdbc:libsql:http://...`, `jdbc:libsql:https://...`, and `jdbc:sqlite:http://...`.
52+
- Maps SQLite dynamic typing to JDBC SQL types and translates Hrana error codes to `SQLException` hierarchies.
53+
54+
4. **`libsql-itests`**:
55+
- All tests run against containerized `sqld` (`ghcr.io/tursodatabase/libsql-server:latest`).
56+
- Includes HikariCP connection pool churn tests and Toxiproxy network toxicity tests.
57+
58+
---
59+
60+
## 3. Code Style & Spotless Formatting
61+
62+
We enforce code hygiene using **Spotless**:
63+
- **Format check**: `mise exec -- ./mvnw spotless:check`
64+
- **Apply format**: `mise exec -- ./mvnw spotless:apply`
65+
66+
CI will fail if files contain trailing whitespace, missing newline terminations, or formatting violations. Run `spotless:apply` before submitting changes.
67+
68+
---
69+
70+
## 4. Testing & Verification Workflows
71+
72+
### Running Unit Tests
73+
```bash
74+
mise exec -- ./mvnw test
75+
```
76+
77+
### Running Integration & Toxicity Tests
78+
Requires a running Docker or Podman daemon:
79+
```bash
80+
mise exec -- ./mvnw clean verify
81+
```
82+
83+
To run a specific test:
84+
```bash
85+
mise exec -- ./mvnw -pl libsql-itests -Dtest=HikariCpIntegrationIT test
86+
```
87+
88+
---
89+
90+
## 5. Coding Standards & Conventions
91+
92+
- **Clean Commits**: Use [Conventional Commits](https://www.conventionalcommits.org/) (e.g. `feat(jdbc): ...`, `fix(codec): ...`, `docs: ...`).
93+
- **No Proprietary Information**: Never commit credentials, private tokens, internal corporate urls, or proprietary notices.
94+
- **Dependency Minimization**: Keep runtime dependencies minimal. Client and codec modules should remain lightweight.
95+
- **Error Handling**: Do not swallow exceptions. Map protocol or transport errors into appropriate `SQLException` or `LibsqlException` types.

0 commit comments

Comments
 (0)