Skip to content

docs(spec): add high-level conventions — paths, NULL defer#200

Open
CGMossa wants to merge 1 commit into
mainfrom
docs/specs-high-level-conventions
Open

docs(spec): add high-level conventions — paths, NULL defer#200
CGMossa wants to merge 1 commit into
mainfrom
docs/specs-high-level-conventions

Conversation

@CGMossa
Copy link
Copy Markdown
Contributor

@CGMossa CGMossa commented May 16, 2026

Unique design choice, where R API is treating NULL as default value by library. This means, that NULL is not a fancy way of writing 0, because it may result in non-zero settings.

AI-written details

Summary

  • Adds two short subsections under the "High-level overview" recording rules that already exist in the implementation but were not written down:
    • Relative paths vs. absolute paths — every dvs command accepts both forms; project-scope / symlink resolution is the library's responsibility, not the caller's.
    • R package — pass NULL in dvs_* functions when you want to defer to the library's default value.
  • Carved out of docs(spec): remaining audit edits (errors, init/add/get/status text + R signatures, audit-log JSON, threading) #149 (spec audit april).
  • The original spec-audit pass also included a "Rust library must never use std::io::{Stdin, Stdout, Stderr}" subsection. Omitted here on purpose — the broader no-CLI/no-R-package coupling invariant on the same topic already landed on main via spec: require dvs core to be free of CLI/R-package concerns #195 / 9df3750, and re-stating a narrower form alongside it would just create drift.

Test plan

  • specs.md renders cleanly on GitHub
  • No dvs_* R wrapper in dvs-rpkg/R/ contradicts the NULL-defer rule
  • No conflict with the library-isolation paragraph already on main

Drafted by Claude (claude-opus-4-7). Reviewed by the author.

Two short subsections under the High-level overview, recording rules
already enforced in the implementation but not previously written
down:

- Relative paths vs. absolute paths: every `dvs` command accepts
  both forms; project-scope / symlink resolution is the library's
  responsibility.
- R package: pass `NULL` in `dvs_*` functions to defer to the
  library's default value.

The "Rust library must never use std::io" rule from the original
spec audit pass is intentionally omitted — the broader
no-CLI/R-package-coupling invariant on the same topic already landed
on main via #195.

Carved out of #149.
@CGMossa CGMossa force-pushed the docs/specs-high-level-conventions branch from a54eeb2 to 3246e32 Compare May 17, 2026 09:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant