7076e4b283* perf(daemon): coalesce metadata writes * refactor(metadata): split repository ops * fix(metadata): harden repository invariants * feat: test coverage and continued refactor work in metadata code * fix(graph): handle path-like explore queries - prefer file path symbol lookup for graph explore\n- sanitize alias FTS queries before MATCH * fix(daemon): quiesce shutdown background work - Interrupt pending DB acquires before worker shutdown - Wait for tracked background coroutines and timers to drain * fix(daemon): cancel repair work on shutdown Blocked embed and post-ingest queues could keep salvage and\nstuck-doc repair alive during shutdown. Consume cancellation in\nrepair retry loops and lock the integrated ServiceManager path\nwith regressions so shutdown fails fast instead of drifting. * perf(metadata): reduce sqlite lock contention * perf(metadata): flatten batch content retries * fix(daemon): align shutdown wait budgets A low shutdown timeout override could expire before ServiceManager\nfinished its 5s+30s WorkCoordinator join path. Share the join\nbudget constants, clamp graceful lifecycle waits to that floor,\nand lock the behavior with a daemon regression. * perf(metadata): bound feedback write waits * perf(metadata): prep batch content before tx * fix(daemon): honor no-embeddings tasks Post-ingest queue tasks dropped the per-task noEmbeddings flag,\nso focused extraction tests still emitted embed jobs and Windows\nCI exercised extra async paths. Preserve the flag through the bus,\nskip embed dispatch when requested, and wake the extraction poller\nimmediately after successful queueing. * perf(daemon): batch fallback metadata writes * feat(perf,docs): optimizations for metadata writes, prompt updates and test improvements * perf(metadata): flatten insert retries * fix(metadata): clear CI portability blockers Use the shared portable ScopedEnvVar in metadata search-query helper tests, add mutators for test reuse, and normalize Statement::bindAll integral dispatch so long long arguments bind consistently across platforms. Add focused regression coverage for the bindAll long long path. * perf(metadata): batch writes and steady bench * fix(daemon): skip inactive post-ingest pollers * perf(metadata): tighten tag and path caches * perf(metadata): cache small batch upserts * fix(daemon): harden embedded host teardown * feat(docs): updating docs policies and language * perf(metadata): tune doc update retries * perf(metadata): bound download retries * perf(metadata): bound download metadata waits * bench(metadata): scope post-ingest content path * fix(daemon): export embedded test hooks * fix(daemon): harden test helper linkage * fix(build): add missing standard includes
121 lines
3.9 KiB
Markdown
121 lines
3.9 KiB
Markdown
# Contributing to YAMS
|
|
|
|
Thanks for your interest in YAMS — contributions of all sizes are welcome.
|
|
|
|
Bug reports, docs fixes, tests, small cleanups, design feedback, and larger features all help. If you're not sure whether something is worth opening, it probably is.
|
|
|
|
## Start here
|
|
|
|
- Please be respectful and constructive.
|
|
- If you're unsure whether something is a bug or a feature request, open the issue with your best guess.
|
|
- If your report is incomplete, that's okay — include what you know and we can help narrow it down.
|
|
- For security issues, please do **not** file a public issue. See `SECURITY.md`.
|
|
|
|
## Reporting bugs and requesting features
|
|
|
|
We use the GitHub issue templates in `.github/ISSUE_TEMPLATE/` for this repository.
|
|
|
|
Helpful details include:
|
|
- `yams --version`
|
|
- platform details
|
|
- exact commands or steps
|
|
- expected vs actual behavior
|
|
- relevant logs or backtraces
|
|
- a small repro, if you have one
|
|
|
|
For feature requests, lead with the problem you're trying to solve. A strong problem statement is often more useful than a fully specified solution.
|
|
|
|
## Development workflow
|
|
|
|
The supported local development workflow is:
|
|
- **Meson + Conan 2**
|
|
- **Ninja**
|
|
- **C++20**
|
|
|
|
Quick debug loop:
|
|
|
|
```bash
|
|
conan install . -of build/debug -s build_type=Debug -b missing
|
|
meson setup build/debug \
|
|
--prefix /usr/local \
|
|
--native-file build/debug/build/Debug/generators/conan_meson_native.ini
|
|
meson compile -C build/debug
|
|
meson test -C build/debug
|
|
```
|
|
|
|
Additional references:
|
|
- GCC flow: `docs/BUILD.md`
|
|
- build system details: `docs/developer/build_system.md`
|
|
|
|
If you're making a small docs-only or narrow change, you do not need to run the entire project test matrix. Please run the smallest relevant check you can.
|
|
|
|
For CI/test speed and stability during local work:
|
|
|
|
```bash
|
|
export YAMS_DISABLE_MODEL_PRELOAD=1
|
|
```
|
|
|
|
## Style and lint
|
|
|
|
- C/C++ formatting is enforced with `clang-format` (see `.clang-format`).
|
|
- Repo-local git hooks live in `.githooks/`.
|
|
- Enable them once with:
|
|
|
|
```bash
|
|
git config core.hooksPath .githooks
|
|
```
|
|
|
|
The pre-commit hook formats staged C/C++ files and can run extra lint checks.
|
|
|
|
## Pull requests
|
|
|
|
Please aim for changes that are:
|
|
- focused
|
|
- well-described
|
|
- tested at the smallest sensible scope
|
|
|
|
A helpful PR usually explains:
|
|
- what changed
|
|
- why it changed
|
|
- how it was tested
|
|
- any follow-up work or tradeoffs
|
|
|
|
## AI usage policy
|
|
|
|
AI tools may be used in an **assistive** role, but we do not want pull requests that are fully or predominantly AI-generated.
|
|
|
|
If you use AI for any part of a contribution:
|
|
- disclose that AI was used and how it was used
|
|
- manually review the entire change before opening the PR
|
|
- be prepared to explain every part of the submitted change
|
|
- make sure the final technical judgment is your own
|
|
|
|
Examples of acceptable use:
|
|
- brainstorming approaches
|
|
- drafting small refactors you fully review and revise
|
|
- generating repetitive boilerplate from a design you already understand
|
|
- improving wording or structure in docs that you then verify
|
|
|
|
Examples of unacceptable use:
|
|
- submitting large, mostly AI-authored patches you do not fully understand
|
|
- using AI to answer maintainers or contributors in your place
|
|
- using AI to generate bug reports, feature requests, or PR discussion as if it were your own firsthand reasoning
|
|
|
|
When in doubt, favor smaller PRs, more disclosure, and more human review.
|
|
|
|
## Commit messages
|
|
|
|
- Use a concise subject line.
|
|
- Add a body when rationale or context would help reviewers.
|
|
- Reference tickets when relevant.
|
|
- DCO sign-off is encouraged: `Signed-off-by: Your Name <you@example.com>`
|
|
|
|
## Project process
|
|
|
|
- Review `GOVERNANCE.md` for roles, decision-making, and releases.
|
|
- Material changes should go through the RFC/ADR process when appropriate (`docs/rfcs`, `docs/adrs`).
|
|
- `CODEOWNERS` reviews are encouraged where applicable.
|
|
|
|
## Code of Conduct
|
|
|
|
We want YAMS to be a welcoming place to collaborate. Please read `CODE_OF_CONDUCT.md`.
|