-
Notifications
You must be signed in to change notification settings - Fork 656
Description
Current Behavior
In our README.md file we have an image:
<img src="assets/monster+rust.png" height="150" align="right">
Link to this line: https://github.com/scylladb/scylla-rust-driver/blob/f59908c54e6b6407112311a3745e32d4bd218d0c/README.md?plain=1#L1
It has not been edited for 4 years. The image is located at https://github.com/scylladb/scylla-rust-driver/blob/main/assets/monster%2Brust.png - again, in the same place for 4 years now.
Today we released new version of the crate, and the page on crates.io no longer shows the image: https://crates.io/crates/scylla/0.15.0
This is because it links to https://github.com/scylladb/scylla-rust-driver/raw/HEAD/scylla/assets/monster+rust.png
- notice the additional /scylla
in the URL after /HEAD
All previous releases were working correctly - most recent one in September (so it is relatively recently introduced bug): https://crates.io/crates/scylla/0.14.0
In this release link leads to https://github.com/scylladb/scylla-rust-driver/raw/HEAD/assets/monster+rust.png
- no more /scylla
after /HEAD
.
Expected Behavior
I expected the image to be correctly displayed, as it always was.
Steps To Reproduce
- Go to: https://crates.io/crates/scylla/0.14.0
- Image works
- Go to https://crates.io/crates/scylla/0.15.0
- Image doesn't work despite the markdown source being the same
Environment
Not sure it is relevant here, but I'll include it anyway.
- Browser: Firefox 130
- OS: Fedora 39
I also verified this on Chromium
Anything else?
No response
Activity
Lorak-mmk commentedon Nov 14, 2024
Oh, I see that there was already #9886
And we do use
readme = "../README.md"
But this issue basically says "this is how cargo works, sorry" - while it did work correctly 2 months ago, so it still looks like a regression.
Turbo87 commentedon Nov 14, 2024
huh, that's interesting. I don't remember any changes that would've caused this, but I'll take a closer look tomorrow.
I guess that depends on the viewpoint. My assumption is that 2 months ago we might not have taken https://docs.rs/crate/scylla/0.14.0/source/.cargo_vcs_info.json#5 into account yet (?). In your case this might look like a regression, but for people with
README.md
files that are actually in nested folders and don't rely on the cargo magic this would have fixed their relative paths.Lorak-mmk commentedon Nov 15, 2024
What is the correct / recommended way to use relative image link in our situation?
epage commentedon Dec 10, 2024
Linking out to any potential cargo-related changes:
package.license-file
into the package root oncargo package
.readme
cargo#10548 (Cargo 1.62) did the same forpackage.readme
cargo package
to include.cargo_vcs_info.json
even when--allow-dirty
is used. However, looking through old versions ofscylla,
I'm always seeing.cargo_vcs_info.json
so this is unlikely to have made a difference.Besides moving of files, there are also symlinks.
cargo package
reads the target for symlinks and includes them in the.crate
file. This means that if yourpackage.readme = "README.md"
is actually for a symlink to../README.md
orfoo/bar/README.md
, Cargo will write the content toREADME.md
and the links could also be offPotential options on cargo's side
.cargo_vcs_info.json
any file remapping we do, explicitly and through symlinkskornelski commentedon Dec 22, 2024
For authors, I recommend using absolute image URLs in the README.
The relative URLs in README are a fiction with no basis in any web standard. Making these URLs work as expected relies on reverse-engineering custom URL schemes of 3rd party services.
The rewriting of the URLs is full of annoying edge cases due to symlinks,
../README
paths, location of the crate within repo (which can be different than the location of the README), and the need to normalize..
in URLs in multiple different ways, also in a way that is host-specific. The assets may exist only at a specific commit or branch the crate has been published from, but Cargo doesn't always have this information.README: Use absolute link for image
Lorak-mmk commentedon Dec 23, 2024
We'll change the url to the absolute one.
It is a bit sad that relative urls don't work well, because now the link in README doesn't refer to the file in the repo in the same commit, but to the outside file that just happens to be the same because we don't change the logo.
Btw is there a way for us to test crates.io rendering without releasing a new version of the crate?
Turbo87 commentedon Jan 3, 2025
you can release to https://staging.crates.io/ if you want. we don't give any stability guarantees for that environment though :D