dbx/agents/docs/release-checklist.md

Release Checklist

Use this checklist before pushing release tags or publishing DBX agent jars.

1. Confirm Scope

• Review the recent commits:

git log --oneline -10

• Confirm the working tree is clean before tagging:

git status --short

• Check that each intended agent change touches the right module directory, common, test-support, docs, or workflows.
• Avoid mixing unrelated driver updates, behavior changes, and release-only edits in the same commit.

2. Local Verification

On this workspace, use the local JDKs under /private/tmp:

env JAVA_HOME=/private/tmp/dbx-jdk/jdk-21.0.11+10/Contents/Home \
  ./gradlew \
  -Dorg.gradle.java.installations.paths=/private/tmp/dbx-jdk/jdk-21.0.11+10/Contents/Home,/private/tmp/dbx-jdk8/jdk8/Contents/Home \
  test shadowJar --continue

Also run the lightweight validation gates:

python3 -m unittest discover -s scripts -p '*_test.py'
python3 scripts/validate_agents.py
python3 scripts/validate_agent_jars.py
git diff --check

The package tests require the zstd CLI.

Expected result:

• Python script tests pass.
• Agent validation passed.
• Agent jar validation passed after shadowJar has produced jars.
• git diff --check prints nothing.
• Gradle finishes with BUILD SUCCESSFUL.

3. Agent Contract Checks

For changed agent modules:

• executeQuery delegates to JdbcExecutor.execute.
• No module-local SQL prefix classifier is present.
• No module-local result row cap is present.
• Statement.execute(...) is used for arbitrary user SQL.
• Metadata methods return stable ordering for schemas, tables, columns, indexes, foreign keys, and triggers.
• User-controlled schema and table names are passed through prepared statements or quoted with JdbcIdentifiers.
• connect stores one connection, disconnect closes and clears it, and testConnection closes its temporary connection.
• A behavior test exists:
  • Use JdbcExecutionBehaviorTest and JdbcMetadataBehaviorTest for agents with a local/embedded test database.
  • Use JdbcFakeExecutionBehaviorTest for agents that require unavailable external drivers.
  • Use targeted JdbcMetadataSqlFake tests for metadata SQL that must interpolate quoted identifiers.

4. Registry And Module Checks

Run:

python3 scripts/validate_agents.py

This checks:

• versions.json keys match included agent modules in settings.gradle.
• Root Gradle conventions define agent archive names.
• Agent manifests define Agent-Label.
• Agent manifests define Main-Class.
• Agent Main-Class source exists and the built jar contains the matching .class.
• Forbidden legacy execution patterns are absent.
• Disallowed JVM source/build DSL residue is absent outside Gradle output directories.

When adding or removing an agent, update these files together:

• settings.gradle
• versions.json
• README.md
• Agent module build.gradle for driver dependencies and manifest attributes
• Root build.gradle only when the module needs non-standard shared build behavior

5. Driver Packaging

For bundled drivers:

• Verify the dependency is redistributable.
• Prefer Maven dependencies over checked-in jars.

For external drivers:

• Use implementation fileTree(dir: 'libs', include: ['*.jar']).
• Set the manifest attribute:

attributes(
    'Agent-External-Driver': 'true'
)

• Confirm release registry generation emits external_driver_required: true.

Current external-driver agents include BigQuery. SunDB used to carry the flag; its vendor JAR is now vendored under drivers/sundb/libs/ and bundled into the Agent, so it is a normal bundled driver again.

6. JRE Selection

Java agents are built for the default JRE key 21, backed by JDK 21 in the release workflow. Native agents do not require a JRE.

If another agent needs a different runtime, update the release workflow JRE detection logic.

• Document why in the module or release notes.
• Verify DBX can download the matching runtime artifact.

7. CI Expectations

The CI workflow runs on main and pull requests:

python3 -m unittest discover -s scripts -p '*_test.py'
python3 scripts/validate_agents.py
./gradlew test shadowJar --continue
python3 scripts/validate_agent_jars.py

Do not tag a release while CI is failing on main.

8. Release Tag Flow

Release workflow runs on tags matching agents-v*.

Before tagging:

git status --short
git log --oneline -5
git tag --list 'agents-v*' --sort=-creatordate | head

Choose a new tag that does not already exist locally or on GitHub. For example:

RELEASE_TAG=agents-v0.3.0
git tag --list "$RELEASE_TAG"
git ls-remote --tags origin "$RELEASE_TAG"

Both commands should print nothing before you create the tag.

Create and push the tag:

git tag "$RELEASE_TAG"
git push origin main
git push origin "$RELEASE_TAG"

The release workflow will:

• Resolve the effective previous module versions from the post-release version-sync commit after the previous agents-v* tag.
• Bump and build only changed Java or native agent modules.
• Download unchanged single-driver packages and JRE archives from the previous immutable release, then verify filenames, versions, platform coverage, sizes, and SHA-256 digests before reuse.
• Generate agent-registry.json.
• Create full offline platform ZIPs from raw staging files.
• Create one .tar.zst package per Java or native driver.
• Publish offline ZIPs, single-driver packages, JRE archives, and the registry.

9. Post-Release Verification

After the GitHub release finishes:

• Download or inspect agent-registry.json.
• Confirm every expected agent appears under drivers.
• Confirm labels preserve spaces, for example Google BigQuery.
• Confirm Java agents use JRE key 21.
• Confirm external_driver_required is correct.
• Confirm every jar URL, sha256, and size is present.
• Spot-check at least one agent jar manifest:

unzip -p dbx-agent-h2.jar META-INF/MANIFEST.MF

10. Known Follow-Ups

• Gradle currently reports deprecated features that will be incompatible with Gradle 10. Use --warning-mode all in a separate cleanup task.
• Commercial or external-driver agents still need manual smoke tests with real driver jars and databases.
• Add real containerized smoke tests only one database family at a time.