akiomik / akiomik/bela-rs

Links out of the package dangle on crates.io, and the rule for them is stated but not followed

オープン
#159 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
documentation
主要言語
Rust
スター
1
フォーク
0
平均マージ
5時間 19分
マージ済み PR(30日)
26

説明

`bela-sys/Cargo.toml` and `bela/Cargo.toml` both set `readme = "README.md"`, so both files are rendered on crates.io with no repository around them. A link that walks out of the package directory has nothing to walk to there.

`bela/README.md` knows this and says so, at its `docs/fft.md` link:

> Both links are absolute because this file is read on crates.io, where the repository around it is not there.

Neither file follows it. Counted on `docs/scope-inventory` (`grep -n '](\.\./' bela/README.md bela-sys/README.md`), **fourteen links leave a package directory**: nine in `bela-sys/README.md` — `docs/fft.md`, `docs/board-facts.md`, `docs/midi.md`, `docs/scope.md`, `bela/README.md`, and `docs/cross-compile.md` four times — and five in `bela/README.md`, the file that states the rule: `bela-sys`, `docs/multithreaded-rendering.md`, the repository `README.md`, and `docs/cross-compile.md` twice.

Nothing here is broken in the repository — every one resolves on GitHub. It is only the published rendering that loses them, which is why it has gone unnoticed.

## Why this is not a "make them all absolute" one-liner

An absolute link pins a branch. `https://github.com/akiomik/bela-rs/blob/main/...` follows `main`, so a crates.io page for 0.8.1 sends its reader to whatever the file says now. That is fine for `cross-compile.md`, which describes a procedure, and less fine for anything describing what a version has. The two absolute links already in `bela/README.md` accept that trade; a sweep should decide it deliberately rather than inherit it fourteen more times.

The alternative is to stop linking out of the package and name the path in prose, which is what `bela`'s rustdoc does with `docs/`: 43 of its 44 mentions are prose and exactly one is a link. That reads worse in a README and never dangles.

A third answer is to package the files — `include = [...]` in each `Cargo.toml` — which would make the relative links correct where they are read. That has its own cost: `docs/` is 3400 lines and would ship with both crates.

Any of the three is fine. What is not fine is the current state, where the rule is written down in one file and followed in neither.

Found while reviewing #157, which added a fifteenth such link, made it absolute, and then took the absolute form back out rather than widen a documentation pull request into this.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

Read bela-sys/Cargo.toml, bela/Cargo.toml, and both package READMEs to understand how crates.io renders them. Run grep -n '](\.\./' bela/README.md bela-sys/README.md from docs/scope-inventory, then compare the three resolution approaches described in the issue before confirming the preferred direction. Done means the published README links no longer dangle and the stated linking rule is followed.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
rust
領域
documentation
issue の種類
ドキュメント
難易度
3/5
見積もり時間
1〜2日
活発さ
活発
明瞭さ
おおむね明確
初心者へのやさしさ
45/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。