Thank you for your interest in contributing to pycubrid.
Write GitHub issues, PRs and comments in English; localized documentation remains welcome, and no specific translation tool is required.
We welcome issues proposed by users, not only pull requests solving maintainer-written tasks. Confusing documentation or setup, missing regression tests, unexpected behavior, error messages, accessibility and usability problems are all useful observations. Open an Improvement Idea from New issue; one clear observation is sufficient. You do not have to identify the root cause, write code, design a solution or supply acceptance criteria just to report it. The maintainer will assess duplication, evidence, scope, priority and testable completion conditions during triage.
Search for similar reports when practical; do not include secrets, private data or security vulnerabilities in public issues. An idea is not permission to change public APIs or skip design, CI, security or release reviews. A separate issue is not compulsory solely to precede a small PR where this repository's contribution and implementation rules permit direct PRs. Check open PRs, owners and existing issue claims before coding.
When a community report leads to a fix, link the originating issue and
acknowledge its verified reporter as a reporter in PR discussion. Keep
verified code-author/co-author credits separate, respecting the existing
release-note credit style and publication checks. When relevant, a curated
release note may distinguish reported by @handle from the implementation
author; do not invent identities, credit bots as people, or make this a
mandatory boilerplate field.
- Python 3.11+
- Git
- Docker (for integration tests)
git clone https://github.com/cubrid-lab/pycubrid.git
cd pycubrid
python3 -m venv venv
source venv/bin/activate
# Contributor tools are PEP 735 dependency groups in pyproject.toml, not extras,
# so `--group` needs pip 25.1 or later (`uv pip install -e . --group dev` also works).
python -m pip install --upgrade pip
pip install -e . --group devThe dev group includes the test, lint, security and release groups.
Install a single group when only that tool set is needed, for example
pip install --group docs for the documentation site or
pip install -e . --group dev --group mutation for mutation testing. The former
pip install -e ".[dev]" extra no longer exists; it is replaced by
pip install -e . --group dev (#784).
make doctor then confirms that every required tool runs from that environment;
it exits non-zero, without a success line, when one is missing or broken.
make help lists the other targets grouped by purpose.
make testmake test and make integration also write test-results/ (JUnit, summary.json with
PASS/FAIL/INCOMPLETE, environment.json; gitignored, removed by make clean); see
docs/DEVELOPMENT.md for the files. CI writes the same
layout, appends each lane's summary to the job summary and uploads test-results/ as a
7-day artifact named test-results-<lane>-... on every run, pass or fail.
make integration # Docker broker on localhost:33000
make integration CUBRID_TEST_PORT=33522 # use a free port if 33000 is takenmake integration (through scripts/run_integration.py) waits for readiness,
fails if the broker never comes up or if every selected test skips, and always
removes what it created, also on Ctrl-C or SIGTERM. It runs in its own Compose project
(pycubrid-it-<time>-<pid>, or INTEGRATION_PROJECT=<name>) and deletes that project's
volumes (down -v), so it never touches a make docker-up lab. To test an
already-running server, set the endpoint explicitly:
CUBRID_TEST_HOST=127.0.0.1 CUBRID_TEST_PORT=33522 \
pytest tests/ -m "integration and not slow and not tls" -vFor a database that stays up between runs, use the manual lifecycle. The broker is
published only on 127.0.0.1; CUBRID_VERSION and CUBRID_TEST_PORT override the
image tag and host port:
make docker-up # start CUBRID on 127.0.0.1:33000
make docker-down # remove container and network, keep the data
make docker-clean # DESTRUCTIVE: also delete the data volumesCUBRID_TEST_URL or CUBRID_TEST_HOST enables integration tests; the
endpoint comes from the per-field CUBRID_TEST_* variables, then the URL, then
localhost:33000/testdb as user dba. With nothing configured, integration
tests skip; with an endpoint configured but unreachable, they error instead
of skipping. See Integration Tests.
The dedicated CI TLS lane selects integration and tls against an SSL-enabled
broker. For local broker/certificate setup, follow the existing
async TLS instructions.
Record live checks not run and their reason; maintainers coordinate missing
broker/version coverage for connection or protocol changes.
This project uses Ruff for linting and formatting. Both checks below leave files
unchanged; make check runs them with typecheck, security and docs-reason-check.
make lint # ruff check
make format-check # ruff format --checkTo auto-fix:
make formatActivate the project development environment (pip install -e . --group dev) before
running Make or pre-commit. The Ruff and Mypy pre-commit hooks are repo: local,
language: system hooks that invoke python3 -m ruff/python3 -m mypy from that
same active environment, so there is a single source of truth for each tool's
version: the exact pin in pyproject.toml. Activate that environment (or a venv
where it's installed) whenever a commit should run the hooks; otherwise
Ruff/Mypy are missing or a stale/global version silently runs instead of the
pinned one. make tooling-check verifies the installed Ruff/Mypy versions
against those pins and confirms the hooks are wired to run through the active
environment. Make and CI share LINT_PATHS (pycubrid tests scripts demos examples) with explicit Python/pyi discovery and hook types, so Markdown is not
reformatted; strict Mypy (the package plus the tests/typing_self_contract.py
static contract in make typecheck) remains separate, and its pre-commit hook
explicitly checks pycubrid/.
When updating either tool, change its pin in the lint dependency group of pyproject.toml,
reinstall the dev group, then run make check and pre-commit run --all-files; there is no
separate hook revision to edit. The drift gate rejects missing/ambiguous pins,
an installed version that no longer matches the pin, and narrowed scopes.
Dependabot's root uv entry updates pyproject.toml and uv.lock together.
Its updater uses its own installed uv version; CI qualifies the resulting lock
with the pinned uv version before running the installed pre-commit tools.
All contributions follow a tool-neutral review process (human-authored,
OpenCode, Codex, Claude Code, ChatGPT, Copilot, or other tools). Required
GitHub Actions CI and maintainer merge judgment apply uniformly; Oracle,
Copilot and agent-review are optional advisory inputs. Local tests are
recommended but their absence is not a separate merge gate. Preserve
existing security-sensitive path review and release safeguards.
- Keep changes focused and explain the motivation in the PR description.
- Add or update tests for behavior changes.
- Run
make test(offline) locally when practical, andmake verify(make check,make test, then the livemake integrationlane; needs Docker) for a full verification. Required GitHub CI validates the final PR head; report commands/results and gaps. - Run integration tests for connection/protocol-related updates.
- Update
CHANGELOG.mdfor user-visible changes.
.github/CODEOWNERS requests maintainer review automatically for release, CI,
security-policy and wire-protocol/connection paths. It only routes reviews: it is
not a security boundary, and other changes do not wait on a code owner.
Outside contributors provide motivation, implementation, tests and affected docs. Maintainers coordinate review, integration coverage and release classification. These project tools are not an installation prerequisite for external contributions. Preserve contributor authorship; add tool attribution only when that tool actually produced a commit.
If docs are unnecessary, put a real reason on a standalone physical source line beginning
Docs: not needed -. Empty text, <reason>, quotations, comments and fenced examples
do not grant an exemption. The line may be adjacent to ordinary prose; it does not
need its own paragraph. The existing docs-not-needed label is a separate
maintainer-controlled exception; neither docs exception bypasses code, security or
release checks.
Up to three leading spaces are allowed; tab/four-space code examples and raw HTML
blockquote/pre/code blocks do not grant an exemption.
For translation help, name the missing language(s) and explain the constraint in
the PR body. That request does not authorize deferral. Maintainers explicitly approve
the existing translations-deferred label and own the recorded follow-up. Korean
README synchronization remains required; other translations remain advisory.
When changing docs, regenerate docs/llms-full.txt with
python scripts/generate_llms_full.py (it also copies the canonical
docs/llms.txt index to the root llms.txt; edit only docs/llms.txt, and CI
fails if either generated file is stale) and run the existing site check
mkdocs build --strict after installing its documented tooling
(pip install --group docs). python scripts/check_docs_links.py reports broken local
links, anchors, unclosed code fences and missing commands, as the required docs-check
CI job does. AI review feedback is separate from commands
actually executed; report both accurately, including gaps and existing warnings.
Maintainers update shared workflow callers through a reviewed upstream commit SHA:
verify the target workflow and its workflow_call inputs at that commit, update
callers together and run required checks. The shared doc-lint workflow still fetches
main-based configuration/scanner assets, so caller pinning does not freeze those assets.
agent-review is optional diagnostic information, not a required check,
a code approval or a condition of merging. The current script may still
summarize review records using legacy tool-specific evidence classifications;
that output is not the project's acceptance policy. Do not make its
check name a protected required context: a PR may impersonate GitHub Actions
check names. Reviewers assess any useful findings independently.
The tool-neutral merge policy is: required GitHub CI passes at the relevant head, verified blocking issues are addressed, and the responsible maintainer makes the final decision. Release, security and protected-path requirements continue to apply, regardless of coding tool. First-time fork workflows may require maintainer approval to run; this is an Actions security control.
Issues own implementation and acceptance in the repository whose files change.
Provide a self-contained local problem, scope, owner, tests, and closure
decision. Sibling repositories may be cited with Refs owner/repo#N when they
supply a real dependency or compatibility contract; their priorities and
completion are not inherited. Close only this repository's issues (Closes #N).
PRs with no local issue may state N/A and a reason. The existing PR title check
rejects direct cross-repository issue-closing keywords, including emphasized or
linked ones, in the PR body, the PR title and commit messages. The title and
commit messages make up the squash commit and are read as plain text; an edit to
the squash message at merge time is not checked. In the body, the check ignores
fenced and indented code blocks and HTML comment blocks only where it can follow
the Markdown exactly, so anything uncertain is checked: code and comment blocks
inside list items, footnotes and block quotes are always checked; after a fence
it cannot track (in a list item, block quote or raw HTML, on an indented line,
or as a line that only looks like a fence), later fences and comments are
checked; after anything that may start an HTML tag, even in prose or inline
code, later comments are checked; and after a raw-text element name such as
<textarea> or <select>, nothing is ignored. Inline code and inline comments
are always checked. The one exception is a Dependabot PR body, which quotes
upstream release notes: a link it rewrote to redirect.github.com, which GitHub
does not take as a closing reference, may name an issue outside cubrid-lab. Its
other references, its title and its commit messages are checked as usual.
External contributors do not need to install internal agent tools or create
duplicate work.
An unassigned good first issue is open to human contributors, including contributors who direct and review AI-assisted code. You may begin work and open a PR without prior maintainer permission, GitHub Assignee access, or any internal agent tool.
Before working, check the issue's Assignees, comments and open PRs. A brief comment that you plan to contribute is encouraged but optional: it is coordination, not an approval requirement or an exclusive reservation. If the issue is already claimed or a PR is in progress, ask before duplicating or taking over that work. Maintainers manage Assignees and labels; lack of self-assignment privileges does not block a human contributor's PR.
Maintainer-operated autonomous agents are different from human-directed AI-assisted contributions: an agent may not consume a newcomer-reserved good first issue unless a maintainer explicitly authorizes that specific issue and assigns the implementer before coding. Broad backlog-fixing or release requests do not count.
Normal testing, docs and review requirements still apply. Maintainers decide whether and when to merge.
This section covers pull request titles and commit subjects in this repository. Issue titles use a type-only prefix (feat:, bug:, etc.) without a required scope; follow the issue forms and local guidance in AGENTS.md. Pull requests are squash-merged and the pull request
title becomes the commit title on main, so the pull request title is the one
that must be right. The PR title check enforces it.
type: description
type(scope): description
type!: description
type(scope)!: description
- type (lowercase, exactly one of):
feat,fix,docs,test,perf,refactor,ci,build,chore,style,revert. - scope is optional: lowercase letters, digits,
-or_, such ascompiler,aio,depsorrelease. !before the colon marks a breaking change. Follow the repository's release policy for breaking changes as well.- 1.x compatibility: protect the PEP 249/DB-API core. A shipped
project-specific public extension is not automatically provisional;
breaking changes to one require an issue-specific maintainer decision,
assessed user impact, migration instructions and a reviewed MINOR release.
Warn in an earlier release when practical; ordinary extensions have no
fixed 28-day wait, while Compat retirement keeps its existing 28-day rule. Update the
public API baseline when its tracked surface changes. Do not implement or
merge an extension removal simply because it is not in PEP 249; see
RELEASE_POLICY.md§3. External contributors may propose changes without advance approval. - Exactly one space after the colon.
- description: English and specific (name the function, type or behavior that changed). Start with a lowercase letter unless the first word is an API name, acronym or proper noun. No trailing period.
- No bracket, status or priority prefixes (
[Bug],[WIP],Track:,epic:,P1). Open a draft pull request for unfinished work; priority and size are labels. - No issue or pull request numbers in the title. Put
Closes #123orRefs #123in the pull request body. GitHub appends the pull request number, for example(#456), to the squash commit by itself.
| Type | Use for |
|---|---|
feat |
A new user-facing capability |
fix |
Corrects wrong behavior, including security fixes |
docs |
Documentation only |
test |
Tests only |
perf |
Faster or lighter with no behavior change |
refactor |
Restructuring with no behavior change |
ci |
CI workflows and their configuration |
build |
Packaging and the build system |
chore |
Maintenance: releases, dependency bumps, housekeeping |
style |
Formatting only |
revert |
Reverts an earlier change; name it in the description |
Examples:
fix(protocol): keep the CAS session after OUT_TRAN
feat(aio): add a charset connection option
docs: document JSON as_numeric() input limits
chore(deps): bump ruff from 0.16.8 to 0.16.9
chore: release v1.9.0
refactor(compiler)!: drop legacy LIMIT rendering
Issue forms prefill a type prefix; keep it and write the rest of the title the same way. A tracking issue (epic) uses the type of the work it tracks.
Maintainers merge with squash merge only and keep the pull request title as
the commit title. Branch commits are squashed into the commit body, so keep
their messages meaningful and keep any Co-authored-by: trailers intact.
Contributors never release. Add user-visible changes under ## [Unreleased] in
CHANGELOG.md, and do not change __version__ or add a dated ## [X.Y.Z]
section in an ordinary PR: a merged version change is what starts an automatic
release. Maintainers use the PR-only release-please.yml generator; curated Unreleased and Upgrade notes remain reviewed in CHANGELOG. Freeze the candidate with autorelease: review before editing its notes, and start CI at the final bot-updated head; see
RELEASING.md. Before merging a release PR, maintainers complete its
release review checklist.
Search for an existing issue first, then use the closest issue form. Keep its
prefilled title prefix; for a custom issue, use a type-only prefix such as bug: or feat: without a module scope.
Reporters describe impact and reproduction; they do not need permission
to apply GitHub labels. Maintainers assign a type label, one
priority: <value> and one size: <value> label (plus area: when relevant).
Topical labels such as testing may also be present.
Human-submitted CLI/API issues with incomplete metadata receive
status: needs triage. The maintainer corrects the metadata and removes
that label. Workflows creating issues with GITHUB_TOKEN must set the title
and labels themselves: GitHub does not start another workflow from that event.
When filing an issue, include:
- Python version
- CUBRID server version
- Minimal reproduction snippet
- Full traceback or error output
Describe urgency and estimated effort. Maintainers or triagers assign the actual
canonical priority:/size: GitHub labels; reporter label permissions are not required.
pycubrid runs an adversarial "Bug Hunt" test layer (property fuzzing, protocol fuzzing, state machines, metamorphic parity, fault injection, differential, mutation, resource/soak). Every defect surfaced by any of these — or by manual review or downstream dogfooding — MUST follow this cycle before the fix lands:
Bug
→ Minimal reproduction
→ GitHub Issue (label: bug + area:)
→ Failing regression test (committed FIRST, red)
→ Fix
→ Permanent regression contract (the test is now green and kept)
Rules:
- No bug fix without a regression test unless it is technically impossible to write one; if impossible, say so explicitly in the PR.
xfailrequires a linked issue. Use@pytest.mark.xfail(strict=True, reason="issue #NNN: ...")for a known-but-unfixed defect so the guard flips to a hard failure (XPASS) the moment the bug is fixed, forcing thexfailmarker to be removed in the fixing PR.- No blanket
|| trueor bareexcept: passto hide failures in test or CI code. - An unexpected
XPASSis a signal, not noise: the referenced bug is fixed — remove thexfailand assert the correct behavior in the same PR. - Classify known limitations as driver / server / upstream so a reader can tell whether the divergence is pycubrid's responsibility. Documented server-behavior and implementation-difference divergences are pinned in the relevant test (e.g. the CUBRIDdb differential suite) rather than left as silent skips.
Worked example: issue #362 (Lob.read silent truncation) was found by the
LOB adversarial suite, filed with a minimal repro, guarded by a strict
xfail regression test, then fixed — the xfail became a passing assertion
in the fixing PR.
See RELEASE_POLICY.md §7 for where behavior-change
classifications are recorded.
tests/test_version_differential.py (#351) runs the same Hypothesis-generated
values and statements against CUBRID 10.2, 11.0, 11.2 and 11.4 at once and
compares what pycubrid exposes: error class/errno/sqlstate, rowcount,
lastrowid, description, and each fetched value's Python type and value.
It runs in the version-differential job of integration-full.yml (release
workflow_call and manual workflow_dispatch, not per PR). Locally, start one container per
version and point the suite at them:
CUBRID_VERSION_MATRIX="10.2=127.0.0.1:33102,11.0=127.0.0.1:33110,11.2=127.0.0.1:33112,11.4=127.0.0.1:33114" \
CUBRID_TEST_HOST=127.0.0.1 CUBRID_TEST_PORT=33114 \
python -m pytest tests/ -m "integration and version_matrix"A divergence passes only when a VersionDifference in
tests/helpers/version_matrix.py explains it: a reason, a link to the CUBRID
change, the versions that differ, the fields allowed to differ, and a tag the
generator attaches to workloads that can hit it. Each entry also has a
deterministic probe that fails when the difference stops reproducing. Any
other divergence is a driver bug (fix it or file it) or an undocumented
server change (confirm it outside pycubrid, e.g. with csql, then document
it).
Some work needs a script, repair tool, probe, dataset or workflow that is meant to be short-lived. Such a tool is acceptable when it is labeled as temporary, so it does not quietly become permanent maintenance.
- Record it in the PR that adds it (PR description or the tool's docstring): why it exists, the local issue and owner, the event that completes it or triggers its removal, where the evidence it produces will live, and the next review point. If the end date is unknown, name the event that reopens the decision; an unknown date does not mean the tool stays forever.
- Run one-time work locally or manually. A one-off repair or profiling run does not need a CI job. A permanent CI job or test harness for a short-lived tool must explain what it protects that existing checks do not, and what it will cost to maintain.
- Review it at the trigger in the existing local cleanup issue: remove the tool, or record a concrete remaining caller and a new, bounded review trigger.
- Map callers before removing it: source imports, tests and fixtures, Makefile targets, CI path filters, release and packaging steps, docs, dependency declarations and compatibility promises. Zero search hits inside this repository do not prove that nobody runs the tool from outside it. Remove only confirmed-irrelevant pieces in a small PR that gives a path-by-path remove or keep reason and runs the usual tests, build and docs checks. Do not add a cleanup-only CI job.
Stable release tooling, compatibility paths, reproducible tests and legitimate diagnostic tools are not temporary and stay supported under this rule.
Example: scripts/_profile_scratch.py was added in #962 as the per-run scratch
table helper for scripts/profile_execute.py and scripts/profile_fetch.py.
The repository cleanup in #1168 was its review trigger. The caller map found
both profilers importing it, docs/PERFORMANCE.md (English and Korean) and the
performance issue form documenting those profilers, and
tests/test_profile_scratch.py testing it, so it was kept as a maintained
helper. Its next review point is the benchmark consolidation in #1209.
Follow the CI execution policy. PR smoke is representative, not full-suite/coverage evidence. Run relevant regression tests locally and report commands/results; request exact-head full validation where compatibility requires it.
Before coding, agree the issue's problem, expected behavior, scope, completion criteria and validation method. Keep the body as the current specification; record dated progress in comments. Maintainers reconcile closed dependencies and completed checklist items after a related merge or handoff. Preserve the original reproduction's revision and limits: older evidence is not proof of current behavior. Priorities/sizes belong in labels, execution order in the backlog tracker. Research closes on a documented decision, not an implied promise to implement every proposed option.
For human-led contributions to an unclaimed issue, GitHub Assignee access and
maintainer preapproval are not required. Check existing Assignees, comments and
open PRs, and coordinate before overlapping another contributor's work.
Maintainers manage assignment and handoffs. Maintainer-operated autonomous
agents must be assigned before implementation and need explicit authorization
for each newcomer-reserved good first issue.
A reviewer does not need to be an issue assignee.
Use the issue and PR's actual state as evidence. Classification, authorization, implementation, review and completion are different decisions:
- Intake / triage: A newly filed issue starts with
status: needs triage. Check evidence or reproduction, duplicate open/closed issues and overlapping PRs, repository scope, type, priority, size, dependencies, and verifiable acceptance criteria. A maintainer removes the intake label only after confirming the saved GitHub metadata. Do not infer priority, size, or triage completion automatically from the title or an AI suggestion. - Ready: Triage completion alone does not authorize development. Record the Ready decision in the issue only when the intended outcome and non-goals are bounded, blockers have been resolved, and any repository-specific product, architecture, safety or compatibility decisions have been accepted. Unresolved research remains investigation; blocked work records its dependency and next action.
- In Progress: Before maintainer-directed or autonomous implementation, identify the actual implementer in the GitHub Assignee field, check whether another open PR already owns the change, and link the implementation PR to its issue. Human-led outside contributors may propose a change on an unclaimed issue without prior assignment or an AI-tool-specific approval; coordinate with existing assignees and follow the local contribution rules.
- In Review: A PR is in review only when its scoped change and verification evidence are available. Check the required CI on the final PR head, test coverage appropriate to the risk, unresolved review findings and any repository-specific independent review or live-system validation. A bot review or passing CI cannot replace an outstanding product/safety decision.
- Done: Record the actual disposition: a merged and validated change, a completed investigation with evidence, or an explained duplicate/not- planned closure. Use an issue-closing PR keyword only if merging actually satisfies its acceptance criteria. A merged PR is not proof that any deferred integration, fault, security or release verification has passed.
Tracking without boards: GitHub Issues and pull requests are the only
workflow tracker. The sole lifecycle label is status: needs triage for
unreviewed intake. Once triage is completed, remove that label after checking
the actual saved issue metadata; do not create status: ready, status: in progress, or other duplicate workflow labels. Record the Ready decision,
remaining dependencies, and next action in the issue. For In Progress,
identify the actual implementer using Assignees and add a concise start/handoff
comment; link the working PR when it exists. In Review is visible from the
linked open, non-draft PR and its actual review/check status. A Blocked
issue records the blocker, responsible party, and unblock condition in a
comment. Done is the issue's Closed state with the recorded validated
outcome or explained disposition, not merely the existence of a merged PR.
Do not configure or depend on GitHub Projects/boards. Priority measures impact,
and size estimates effort; neither represents work-in-progress.
This guidance introduces no new automated merge gate and does not supersede
this repository's design, testing, security, or release requirements.