Contributing

Project Goals

• Deterministic formatting output (same input shape -> same formatted output).
• Zero semantic changes to query evaluation intent.
• Safe support for multiple dialects via explicit adapter behavior.

Development Workflow

1. Create a focused branch.
2. Make small, reviewable changes.
3. Add or update fixtures/tests for every behavior change.
4. Run npm run verify.
5. Open a PR with a concise problem statement and validation notes.

Engineering Standards

• Keep formatter behavior idempotent.
• Prefer fixture-driven tests for syntax coverage and regression safety.
• Avoid broad refactors mixed with behavior changes.
• Preserve backward compatibility unless explicitly versioned as breaking.
• Keep extension settings documented in README.md.

Git Hygiene

• Use conventional commit-style messages (feat:, fix:, docs:, chore:).
• One concern per commit whenever practical.
• Never commit node_modules, out, dist, or editor-local temp files.
• Rebase or merge to keep long-lived branches current before release work.

Test Expectations

• npm run verify must pass before merge.
• Add tests for:
  • parser/dialect entry behavior
  • formatting output changes
  • idempotency for new formatting paths
  • invalid input handling for new syntax paths

Release Readiness (Marketplace)

• Ensure package.json metadata is complete (publisher, repository, bugs, homepage, license, keywords).
• Update CHANGELOG.md.
• Run npm run package:vsix.
• Validate install/format behavior in a clean VS Code profile.

AI-Assisted Contributions

• AI-generated changes must follow the same test and review gates.
• Require explicit test additions for any formatter behavior change.
• Require a human review pass on:
  • dialect preprocessing logic
  • parser error-handling paths
  • printer precedence/parentheses logic