Skip to content

Contributing

Jump to bottom
github-actions[bot] edited this page Sep 26, 2026 · 3 revisions

Contributing

Guide for setting up the development environment and submitting contributions.

Prerequisites

  • Node.js 22+ (.nvmrc points to 24; CI tests 22/24 — Node 20 has reached EOL)
  • npm (comes with Node)
  • Git
  • (Optional) Oracle Database + utPLSQL for integration tests

Environment setup

# Clone the repository
git clone https://github.com/thepaneb/vscode-utplsql.git
cd vscode-utplsql

# Install dependencies
npm install

# Compile TypeScript
npm run compile

Project structure

vscode-utplsql/
├── src/
│   ├── extension.ts         ← orchestrator (entry point)
│   ├── runner.ts            ← executeRun + applyResults/applyCoverage wrappers
│   ├── oracleRunner.ts      ← executeRunOracle (streaming + pool) + utPLSQL schema discovery
│   ├── results.ts           ← canonical result/coverage functions (PRD-44)
│   ├── config.ts            ← settings + env vars reading + resolveConnection
│   ├── connectionProfiles.ts ← connection profile CRUD + picker
│   ├── discovery.ts         ← findFiles + parse + DB-based discovery (PRD-43)
│   ├── suiteParser.ts       ← regex %suite/%test + annotations (pure)
│   ├── junit.ts             ← JUnit XML parsing + stack frames (pure)
│   ├── cobertura.ts         ← Cobertura XML parsing (pure)
│   ├── coverage.ts          ← coverage filename → source URI resolution
│   ├── viewCoverage.ts      ← optional V$SQL view tracking
│   ├── matching.ts          ← URI/folder filtering + result→test matching (pure)
│   ├── codelens.ts          ← parseCodeLensItems (pure) + CodeLensProvider
│   ├── plsqlDeclarations.ts ← declaration coverage derived from source (pure)
│   ├── quickfix.ts          ← SetupValidator + Code Actions
│   ├── decorations.ts       ← inline pass/fail decorations
│   ├── statusBar.ts         ← status indicator
│   ├── scriptRunner.ts      ← SQL script execution (editor/file/folder, PRD-62)
│   ├── debugger.ts          ← DBMS_DEBUG debug adapter
│   ├── dbmsDebug.ts         ← DBMS_DEBUG client (pure SQL/parse)
│   ├── i18n.ts              ← translation runtime (pure)
│   ├── i18nLocales.ts       ← locale catalogs (pure)
│   ├── state.ts             ← session state (pure)
│   ├── types.ts             ← interfaces (type-only)
│   └── test/
│       ├── unit/            ← tests with node --test
│       └── integration/     ← tests with @vscode/test-cli
├── dist/                    ← esbuild bundle (generated; main = dist/extension.js)
├── docs/
│   ├── prd/                 ← Product Requirements Documents
│   ├── functional/          ← functional specification
│   └── wiki/                ← wiki content
├── .github/workflows/       ← CI/CD
├── esbuild.config.mjs       ← bundling (PRD-45)
├── package.json
├── tsconfig.json
├── biome.json               ← linter + formatter
└── README.md

Commands

npm install              # dependencies
npm run compile          # tsc → out/
npm run watch            # incremental compilation
npm run lint             # biome check src/
npm run lint:fix         # biome check --write src/
npm run format           # biome format --write src/
npm run test:unit        # pretest:unit (compile+lint) → node scripts/run-tests.cjs
npm run test:integration # pretest:integration (compile+bundle) → vscode-test
npm run test:coverage    # compile → c8 node --test (thresholds 65/80/70)
npm test                 # = test:unit
npm run bundle           # esbuild → dist/ (actual extension main)
npm run package          # compile + bundle + vsce package → .vsix
npm run sync-prds        # sync PRDs with GitHub issues

Run a single unit test:

node --test out/test/unit/junit.test.js
node --test --test-name-pattern "duration" out/test/unit/**/*.test.js

Debugging

Press F5 in VSCode (.vscode/launch.json configured) to open an Extension Development Host instance with the extension loaded. You can open a PL/SQL project in that window and test the extension interactively.

Extension Development Host with Testing view

If the Extension Host output shows TypeError: Missing dataLength in event (node:inspector), it comes from the JS debugger's experimental Network View, not from this extension. .vscode/launch.json already sets "experimentalNetworking": "off"; if it still appears, set "debug.javascript.enableNetworkView": false in your User settings.

Integration tests with a real database

Create a .env file in the project root (gitignored):

UTPLSQL_CONN=your_user/password@//host:1521/service

Run:

npm run test:integration

Without the env vars, database tests (describeDB) are automatically skipped.

Database test matrix (multiple Oracle versions)

Spin up a real Oracle for integration tests against several versions, one at a time (scripts/db-matrix/run.sh; needs Docker, and ORACLE_AUTH_USER/ ORACLE_AUTH_TOKEN in .env.dbmatrix for the Enterprise images):

npm run db:matrix:list                 # versions: 12.2, 18xe, 19ee, 21xe, 23free
npm run db:matrix                      # whole matrix (one version at a time)
npm run db:matrix -- --only 21xe       # a single version
npm run db:matrix -- --smoke           # fast subset (capabilities + debugger)
npm run db:matrix -- --thick           # thick mode per version
npm run db:matrix -- --clean           # wipe the data volume and recreate

Data is kept in a per-version Docker volume: the first run creates the database (~15–25 min for 18c/19c); later runs boot from it in ~1–2 min. Use --skip-bootstrap when the volume is already prepared. See PRD-72 and the root CONTRIBUTING.md for details.

Alternative utPLSQL floors: each VERSIONS line may declare a 4th field with the utPLSQL version for that database. 12.2 uses v3.1.14 because v3.2.x does not compile on it (PLS-00222); lines without the 4th field fall back to UTPLSQL_VERSION (PRD-84).

Code conventions

Style defined in biome.json and enforced via npm run lint + npm run format:

  • Indent: 2 spaces
  • Line width: 100 characters
  • Quotes: single (')
  • Semicolons: always (;)
  • Trailing commas: always (,)
  • Linter: recommended preset

Contribution workflow

  1. Fork the repository
  2. Create a branch: git checkout -b feature/my-change
  3. Make your changes following the conventions
  4. Run npm run lint and npm test — they must pass
  5. Commit with a clear message
  6. Push and open a Pull Request targeting main

Commit message

Format: <type>: <description> [(PRD-NN)]

feat: add support for dynamic reporters (PRD-10)
fix: fix coverage mapping on Windows
docs: update troubleshooting section

If the change completes a PRD, reference Closes #N in the commit/PR body.

Keeping the README and wiki updated

  • New settings → add to the README configuration table and the wiki Configuration page
  • New commands → add to the README Commands section and the wiki Commands page
  • New behaviors → if relevant for troubleshooting, add to the wiki Troubleshooting page
  • Architecture changes → update the Architecture page

The wiki is automatically synced via workflow when pushing to the main branch (files in docs/wiki/).

Clone this wiki locally