Skip to content

Commit 9c404b1

Browse files
polRkpolRk
committed
chore(ci,docs): add lint/release workflows and contributor docs
 - Add .github/workflows/lint.yml - Add .github/workflows/release.yml - Add CONTRIBUTING.md, RELEASING.md, VERSIONING.md - Update README.md to reference new processes - Update package-lock.json to reflect current setup No functional changes; CI and docs only. Signed-off-by: Vladislav Polyakov <[email protected]>
1 parent 0a9f4ee commit 9c404b1

File tree

7 files changed

+289
-87
lines changed

7 files changed

+289
-87
lines changed

‎.github/workflows/lint.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Lint & Exports
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
lint:
13+
runs-on: ubuntu-latest
14+
concurrency:
15+
group: lint-${{ github.event_name }}-${{ github.ref }}
16+
cancel-in-progress: true
17+
steps:
18+
- uses: actions/checkout@v4
19+
- uses: ./.github/actions/setup
20+
with:
21+
node-version: 22
22+
- run: npm run lint
23+
- run: npm run attw

‎.github/workflows/release.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Release (Changesets)
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
branches: [ main ]
7+
8+
permissions:
9+
contents: write
10+
id-token: write
11+
packages: write
12+
13+
jobs:
14+
release:
15+
if: github.ref == 'refs/heads/main'
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v4
19+
- uses: ./.github/actions/setup
20+
with:
21+
node-version: 22
22+
- name: Create Release Pull Request or Publish
23+
uses: changesets/action@v1
24+
with:
25+
publish: npm run publish-packages
26+
env:
27+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
28+
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

‎CONTRIBUTING.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Contributing to YDB JavaScript SDK
2+
3+
Thanks for your interest in contributing! This monorepo contains multiple `@ydbjs/*` packages.
4+
5+
## Prerequisites
6+
7+
- Node >= 20.19, npm >= 10
8+
- Docker (for integration/e2e tests using local YDB)
9+
10+
## Setup
11+
12+
```bash
13+
git clone https://github.com/ydb-platform/ydb-js-sdk.git
14+
cd ydb-js-sdk
15+
npm ci
16+
```
17+
18+
## Development
19+
20+
- Build all packages: `npm run build`
21+
- Run unit tests: `npm run test:uni`
22+
- Run integration tests (requires Docker): `npm run test:int`
23+
- Run all tests: `npm run test:all`
24+
- Lint: `npm run lint`
25+
26+
## Commit & PR Guidelines
27+
28+
- Keep changes scoped and minimal per PR
29+
- Update relevant READMEs when changing public APIs
30+
- Add/adjust tests alongside code changes
31+
- For breaking changes, include migration notes in the PR description
32+
33+
## Release Process
34+
35+
We use Changesets to manage versions and changelogs.
36+
37+
- Add a changeset: `npx changeset`
38+
- After merging to main, the Release workflow will create a release PR or publish (see .github/workflows/release.yml)
39+
40+
## Running Local YDB for Tests
41+
42+
Integration tests use a local YDB container. CI spins it automatically; locally you can set env vars to reuse your own instance, or rely on the test setup script.
43+
44+
Key envs:
45+
46+
- `YDB_CONNECTION_STRING`, `YDB_STATIC_CREDENTIALS_*`
47+
48+
See `vitest.setup.ydb.ts` for details.
49+
50+
## Code Style
51+
52+
- TypeScript strict mode
53+
- Avoid one-letter variable names
54+
- Prefer explicit types in public APIs
55+
56+
## Questions?
57+
58+
Open an issue or start a discussion in the repository.

‎README.md‎

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
# YDB JavaScript SDK
22

3-
A modular, modern SDK for working with YDB in JavaScript/TypeScript. Supports queries, transactions, types, error handling, authentication, and more.
3+
Modern, modular SDK for YDB in TypeScript/JavaScript.
4+
5+
- Type‑safe YQL queries with tagged templates
6+
- Automatic parameter binding and transactions
7+
- Rich value/type system with `@ydbjs/value`
8+
- Clear errors, retries, and diagnostics
49

510
## Other versions
611

@@ -23,17 +28,13 @@ A modular, modern SDK for working with YDB in JavaScript/TypeScript. Supports qu
2328

2429
## Quick Start
2530

26-
### 1. Run YDB Locally
27-
28-
Start a local YDB instance with Docker: https://ydb.tech/docs/en/quickstart
29-
30-
### 2. Install Required Packages
31+
### 1) Install
3132

3233
```sh
3334
npm install @ydbjs/core @ydbjs/query
3435
```
3536

36-
### 3. Connect and Query
37+
### 2) Connect and Query
3738

3839
```ts
3940
import { Driver } from '@ydbjs/core'
@@ -49,14 +50,6 @@ console.log(resultSets) // [ [ { sum: 2 } ] ]
4950

5051
---
5152

52-
## Installation
53-
54-
```sh
55-
npm install @ydbjs/core @ydbjs/query @ydbjs/value @ydbjs/api @ydbjs/error
56-
```
57-
58-
---
59-
6053
## Documentation
6154

6255
- [@ydbjs/core](./packages/core/README.md)
@@ -67,19 +60,27 @@ npm install @ydbjs/core @ydbjs/query @ydbjs/value @ydbjs/api @ydbjs/error
6760
- [@ydbjs/auth](./packages/auth/README.md)
6861
- [@ydbjs/retry](./packages/retry/README.md)
6962

63+
Project docs:
64+
65+
- [Releasing](./RELEASING.md)
66+
- [Versioning](./VERSIONING.md)
67+
- [Contributing](./CONTRIBUTING.md)
68+
7069
---
7170

7271
## Examples
7372

74-
**Parameterized Query:**
73+
Examples
74+
75+
- Parameterized query:
7576

7677
```ts
7778
import { Int64, Optional, PrimitiveType } from '@ydbjs/value'
7879
const sql = query(driver)
7980
await sql`SELECT ${new Optional(new Int64(100n), new PrimitiveType('INT64'))};`
8081
```
8182

82-
**Transactions:**
83+
– Transactions:
8384

8485
```ts
8586
await sql.begin(async (tx, signal) => {
@@ -88,7 +89,7 @@ await sql.begin(async (tx, signal) => {
8889
})
8990
```
9091

91-
**Error Handling:**
92+
– Error handling:
9293

9394
```ts
9495
import { YdbError } from '@ydbjs/error'
@@ -129,5 +130,6 @@ Copy the appropriate file to your project root to enable secure AI code generati
129130

130131
## Developer Guide
131132

132-
- Build all packages: `npm run build`
133-
- Run all tests: `npm test`
133+
- Build: `npm run build`
134+
- Test (all): `npm test`
135+
- Lint: `npm run lint`

‎RELEASING.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Releasing YDB JavaScript SDK
2+
3+
This document describes how we cut stable releases for all packages in this monorepo.
4+
5+
## Versioning Strategy
6+
7+
- Packages follow SemVer.
8+
- We release coordinated versions across `@ydbjs/*` where feasible.
9+
- Pre-releases use the `alpha` tag; stable uses `latest`.
10+
11+
See VERSIONING.md for details.
12+
13+
## Preconditions
14+
15+
- Node >= 20.19, npm >= 10
16+
- All tests green: `npm test:all`
17+
- Lint clean: `npm run lint`
18+
- Changelog entries prepared via Changesets in `.changeset/`
19+
- No uncommitted files; CI green on main.
20+
21+
## Release Steps
22+
23+
1) Ensure workspace builds and tests pass
24+
25+
```bash
26+
npm run build
27+
npm test:all
28+
```
29+
30+
2) Verify package entry points and exports with ATTW
31+
32+
```bash
33+
npm run attw
34+
```
35+
36+
3) Bump versions and generate changelogs (Changesets)
37+
38+
```bash
39+
npx changeset version
40+
```
41+
42+
4) Publish to npm (stable)
43+
44+
```bash
45+
# Ensure you are authenticated: npm whoami
46+
NPM_CONFIG_PROVENANCE=true npx changeset publish
47+
```
48+
49+
5) Create GitHub Release
50+
51+
- Tag matches monorepo state (e.g., v7.0.0)
52+
- Paste aggregated changelog highlights
53+
54+
6) Announce breaking changes and migration notes
55+
56+
- Link MIGRATION.md sections in release notes
57+
58+
## Alpha → Stable Transition
59+
60+
- Remove `publishConfig.tag: alpha` in packages slated for stable
61+
- Verify dependencies across packages resolve to stable ranges
62+
- Update documentation to remove “alpha” suffixes in install commands
63+
64+
## Smoke Verification
65+
66+
- Run example apps in `examples/`
67+
- Install packages in a fresh project and run a simple query

‎VERSIONING.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Versioning
2+
3+
We use Semantic Versioning for all `@ydbjs/*` packages.
4+
5+
- MAJOR: breaking API changes
6+
- MINOR: backwards-compatible features
7+
- PATCH: bug fixes and docs/typings improvements
8+
9+
## Coordinated Releases
10+
11+
Where possible, packages share the same major/minor to reduce friction:
12+
13+
- @ydbjs/core, @ydbjs/query, @ydbjs/value, @ydbjs/api, @ydbjs/error, @ydbjs/retry, @ydbjs/auth
14+
15+
Internal APIs may evolve without public guarantees. Public APIs are documented in each package README and types.
16+
17+
## Pre-releases
18+
19+
- Pre-releases use the `alpha` tag and semver pre-release identifiers (e.g., 7.0.0-alpha.33)
20+
- Stable releases use the `latest` tag
21+

0 commit comments

Comments
 (0)