# HyperStreamDB Development Guidelines

**Foundation:** These guidelines are rooted in [The Pragmatic Programmer](https://pragprog.com/) principles. See `/memories/STEERING.md` for the full foundational principles that guide all projects.

## Core HyperStreamDB Principles

### Code Quality
- **Always attempt to fix warnings if possible** - Don't ignore compiler warnings; resolve them during implementation (Aligns with: Don't Live with Broken Windows #4)
- Use proper error handling instead of silencing warnings
- Maintain clean build output (zero clippy warnings)
- Type safety is paramount
- Refactor early and often as code is written

### Versioning & Releases
- Version numbers are injected from git tags during build
- `Cargo.toml` and `pyproject.toml` use dynamic versioning from `build.rs`
- Tag format: `v0.X.Y` (e.g., `v0.1.2`)
- All releases should be tagged and pushed with comprehensive release notes

### Licensing & Attribution
- Apache 2.0 / MIT dual license
- Properly attribute optimizations borrowed from iceberg-rust or other Apache-licensed projects
- Maintain THIRDPARTY_NOTICES.md with all third-party code usage
- Include inline code comments for borrowed patterns

### API Design
- Use native Rust names (PascalCase for types: `Cosine`, `L2`, `InnerProduct`)
- Python API uses lowercase for user-facing functions: `metric="cosine"`
- Support both primary parameter names and backward-compatible aliases
- Document all vector distance functions and index parameters

### Testing & Validation
- Unit tests required for new optimizer rules and query optimizations (Aligns with: Design to Test #20, Test Your Software #21)
- Explain() output should show correct index usage and query strategy
- Test suite must pass before any release tagging (Aligns with: Make Quality a Requirements Issue #7)
- Performance benchmarks are part of testing, not optional extras
- Integration tests for query planning changes
- Run full test suite before tagging releases
- Verify explain() output shows correct index detection

### Packaging
- Exclude build artifacts, virtual environments from Cargo.toml (Aligns with: Make It Easy to Reuse #11)
- Ensure PyPI builds succeed without external dependencies
- Test `maturin develop --release` before release tagging
- Dynamic versioning from git tags (build.rs injection)

## Current Focus Areas

### Hybrid Query Optimization
- Support multiple vector columns with ordering
- Compound primary key detection for automatic hybrid search
- Vector search always runs after scalar filters (push-down)
- Proper explain() output showing both scalar and vector execution
- Use tracer bullets: Implement end-to-end before perfecting details (Aligns with: Use Tracer Bullets #14)

### Iceberg-Rust Optimizations
- LIMIT pushdown to file scanning layer
- Row group skipping based on column statistics
- Manifest metadata caching for performance
- Predicate pushdown improvements
- Properly attribute all borrowed code patterns (Aligns with: Communicate! #9, Make It Easy to Reuse #11)

### Observability & Debugging
- Structured tracing via `tracing` crate (no println!) (Aligns with: Program Close to Problem Domain #16)
- Proper log levels (debug, info, warn, error)
- Explain query plans for user visibility (Aligns with: Use Tracer Bullets #14)
- Document query strategy through explain() output
