CONTRIBUTING: document testing and commit/PR organization

[swasik]

Motivation

The Testing section of CONTRIBUTING.md only documented cargo test, and the repo had no written commit/PR organization conventions or agent-facing instructions. This PR documents how contributors actually test and structure changes.

Changes

CONTRIBUTING.md

Testing — two new subsections:

• Validator harness (end-to-end tests): what it is (spawns its own ScyllaDB + Vector Store cluster), building vector-store and vector-search-validator with scripts/run-with-release-toolchain (and why the toolchain-built binaries must be used — glibc compatibility with the ScyllaDB image), running via scripts/run-validator-with-scylla-docker <scylla-image> <vs-bin> <validator-bin> [filters] --verbose, the <group>::<test> filter syntax, and listing test cases.
• Manual testing with the example docker-compose stacks: the docs/examples/docker/docker-compose.yml (CQL / native) and docker-compose-alternator.yml (Alternator / DynamoDB) stacks, how to bring them up and exercise them with docs/examples/quick-start.cql, with a note that this is for local exploration only.

Commit and PR Organization — a new section based on the ScyllaDB patch organization guidelines: small self-contained patches, each individually compiling/correct with sensible ordering, the module: changes subject format (repo components vector-store/validator/scripts/README), specific summaries, ~72-char commit-log lines, non-expert self-contained descriptions, and the why-not-just-what motivation rule for patches and PRs.

Pre-Review Checklist — updated the issue-reference bullets from GitHub issues (Fixes: #XYZ / Reference: #XYZ) to Jira (Fixes: VECTOR-XYZ / Refs: VECTOR-XYZ), since the project no longer uses GitHub issues.

CLAUDE.md (new)

A repository-level agent-instructions file pointing at CONTRIBUTING.md and docs/rust_instructions.md, with a quick reference (format/lint/test commands, OpenAPI regeneration, and a pointer to the Commit and PR Organization section) so the contributor guidelines and Rust conventions are surfaced as repo instructions.

Test plan

Documentation-only change. Verified the rendered Markdown structure and that all referenced paths and scripts exist in the repo.

Refs: VECTOR-763

[Copilot]

Pull request overview

Documents repository testing workflows, contribution conventions, and agent-facing development guidance.

Changes:

• Adds validator and Docker Compose testing instructions.
• Defines commit, PR, and Jira-reference conventions.
• Adds repository instructions for coding agents.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
CONTRIBUTING.md	Expands testing and change-organization guidance.
CLAUDE.md	Adds an agent-facing development quick reference.

Comments suppressed due to low confidence (2)

CONTRIBUTING.md:137

• The referenced CQL file says to wait after CREATE INDEX, but cqlsh -f ignores that comment and immediately executes the ANN query while index creation may still be in progress. This makes the documented manual test race the asynchronous index build. Either provide an actual readiness wait/poll in the example or instruct users to execute the statements interactively and pause at that point.

cqlsh -f docs/examples/quick-start.cql   # create a vector table + index and run an ANN query

CLAUDE.md:21

• This runs tests only for the workspace's default member, crates/vector-store (Cargo.toml:6), so agents following the repository instructions will skip tests in the other crates. Add --workspace to make the command match its unit-and-integration-test description.

- Run unit and integration tests: `cargo test --verbose`.

[QuerthDP]

Looks really good. Please consider my comments

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

CONTRIBUTING.md:168

• Running the whole quick-start with cqlsh -f does not honor its WAIT FEW SECONDS marker: comments do not pause execution, so the ANN query runs immediately after the asynchronous index creation and can fail while the index is not ready. The validator explicitly polls for IndexStatus::Serving (crates/validator/src/common.rs:477-483), and the repository notes that ANN queries against a not-yet-built index error (latte/vector-search/README.md:45-49). Make this an interactive procedure (or add a real readiness poll) instead of executing the file in one shot.

cqlsh -f docs/examples/quick-start.cql   # create a vector table + index and run an ANN query