Skip to content

Update default output path in README.md#210

Closed
victorhooi wants to merge 1 commit into
lablup:mainfrom
victorhooi:patch-1
Closed

Update default output path in README.md#210
victorhooi wants to merge 1 commit into
lablup:mainfrom
victorhooi:patch-1

Conversation

@victorhooi

Copy link
Copy Markdown

Previously, the README seemed to suggest all-smi would write to ./all-smi-record.ndjson.zst in the current directory.

Fixing the readme here to clarify it actually writes to ~/.cache/all-smi by default.

(To be honest, I find that default a bit confusing - but I'm assuming there's some precedent here?)

Previously, the README seemed to suggest `all-smi` would write to `./all-smi-record.ndjson.zst` in the current directory.

Fixing the readme here to clarify it actually writes to `~/.cache/all-smi` by default.
@cla-assistant

cla-assistant Bot commented May 3, 2026

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@inureyes

inureyes commented May 24, 2026

Copy link
Copy Markdown
Member

Thanks @victorhooi , and your instinct is right on both counts: the README was wrong, and the default is more confusing than it should be. I traced it through the code:

Your correction is accurate. The effective default really is ~/.cache/all-smi/records/all-smi-record.ndjson.zst. It comes from Settings::default() always setting record.output_dir = "~/.cache/all-smi/records" (src/common/config_file.rs), which RecorderOptions::from_args_with_settings joins with the default basename even when no config file is present (src/record/mod.rs).

Why it feels confusing- the default is surfaced inconsistently across three places:

  • all-smi record --help still advertises the --output default as all-smi-record.ndjson.zst (src/cli.rs), i.e. the current directory;
  • the source doc comment says the compiled default is ./all-smi-record.ndjson.zst (src/record/mod.rs);
  • only the README (after your fix) says ~/.cache/....

So this PR fixes the README, but --help- where most people look first- would still point at the working directory. On top of that, the effective path is computed by string-matching --output against the magic basename to detect "operator didn't pass -o", which is brittle (the code comment itself says "if that ever changes, update this guard") and has a latent wart: passing -o all-smi-record.ndjson.zst explicitly gets silently redirected into the cache dir.

Cross-platform caveat: the ~/.cache/... default is a hard-coded string expanded via dirs::home_dir() (src/common/paths.rs), not the platform-aware dirs::cache_dir(). So on Windows it lands at C:\Users\<you>\.cache\all-smi\records\... (a Unix-style dotdir in the profile) and on macOS at ~/.cache/... rather than ~/Library/Caches/...- functional, but not where users on those platforms expect cache data. The config path, by contrast, already uses dirs::config_dir() (%APPDATA%\all-smi on Windows), so there's an internal inconsistency worth reconciling too.

Because of that, we'd like to fix this a little more thoroughly: align --help, the doc comment, and the README on one default, make the path resolution explicit rather than sentinel-based, and consider deriving the cache location from dirs::cache_dir() so it's platform-correct. We'll fold your README correction into that change, with credit to you.

One process note: we can't merge this PR as-is because the CLA check is still unsigned. We'll track the fuller fix as a separate issue/PR. Thank you again for catching this and for the clear write-up- the "I find this default a bit confusing" remark is exactly what prompted the deeper look. 🙏

@inureyes

inureyes commented May 24, 2026

Copy link
Copy Markdown
Member

Tracking the fuller fix in #223 : it covers the doc alignment (--help / doc comment / README), de-brittling the default-path resolution, and the cross-platform cache location. Your README correction will be incorporated there with credit. Thanks again @victorhooi! 🙏

inureyes added a commit that referenced this pull request May 24, 2026
* fix: resolve record default output path consistently (#223)

`all-smi record`'s default output path was advertised inconsistently across `all-smi record --help`, the `from_args_with_settings` doc comment, and the README; behind the scenes the default was resolved by string-matching the operator's `-o` value against the magic basename `all-smi-record.ndjson.zst`.

As a side effect of that string-sentinel guard, passing `-o all-smi-record.ndjson.zst` explicitly was silently redirected under `record.output_dir` (the cache dir) instead of being written verbatim to the current directory — a quiet behaviour change no operator would expect from a flag they passed explicitly.

Scope A of the fix (this commit):

- Make `RecordArgs::output` an `Option<PathBuf>` and drop clap's `default_value`. Resolution now happens in `from_args_with_settings`: `Some(p)` is honored verbatim, `None` falls back to `<output_dir>/<DEFAULT_BASENAME>` (or just `<DEFAULT_BASENAME>` when no config is loaded). The brittle basename comparison is gone.
- Introduce a single shared `pub const DEFAULT_BASENAME: &str = "all-smi-record.ndjson.zst"` in `record/mod.rs`, dedupe-ing the literal that was previously inlined in both `cli.rs` and the resolver.
- Align all three doc surfaces (the clap `long_help` on `--output`, the `from_args_with_settings` doc block, and the README record-options table) on the same default-resolution story.
- Add four unit tests for the resolver: no `-o` + no config, no `-o` + config `output_dir`, explicit `-o` equal to the default basename (regression guard for the silent-redirect bug), and explicit `-o` absolute path with and without config.

Scope B from the issue (deriving the cache base from `dirs::cache_dir()` so Windows / macOS land in their platform-correct cache directories) is intentionally deferred per the issue's own recommendation — it changes where existing files live and warrants a separate decision and migration note.

Folds in the README correction originally proposed in #210 by @victorhooi, with credit; that PR could not be merged directly due to an unsigned CLA.

* test: add tilde-expansion coverage for record output resolver

When `record.output_dir` is a tilde-prefixed path (e.g. `~/my-records`), the resolver calls `expand_tilde` before joining `DEFAULT_BASENAME`. The existing `resolve_output_no_cli_with_config_dir` test used an absolute path, so that branch was untouched. The new `resolve_output_no_cli_with_tilde_config_dir` test exercises the expansion call directly and derives its expected value from the same `expand_tilde` helper the resolver uses, making it portable across environments where `$HOME` may or may not be set.
@inureyes inureyes added type:bug Something isn't working status:wontfix This will not be worked on area:ci CI/CD related labels May 26, 2026
@inureyes inureyes self-assigned this May 26, 2026
@inureyes inureyes closed this May 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:ci CI/CD related status:wontfix This will not be worked on type:bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants