Image: Update usage section in README

Created on 5 May 2019  ·  6Comments  ·  Source: image-rs/image

The recommended way of adding dependency from the README is currently

[dependencies]
image = "*"

at https://github.com/image-rs/image/blame/master/README.md#L18-L19

From The Cargo Book:

Can libraries use * as a version for their dependencies?

As of January 22nd, 2016, crates.io rejects all packages (not just libraries) with wildcard dependency constraints.

While libraries can, strictly speaking, they should not. A version requirement of * says “This will work with every version ever,” which is never going to be true. Libraries should always specify the range that they do work with, even if it’s something as general as “every 1.x.y version.”

All 6 comments

Yeah, if we want to include a line like that at all, it should really be image = "0.22.0" (or similar).

We can include a test for this in release.sh if we decide to leave it included in the README and on the exact formt which we'd like to have.

Your comments got me thinking, maybe we should just drop the whole Usage section from README.

If you look at https://crates.io/crates/image, there's an auto generated widget thingy on top which suggest the proper edit for Cargo.toml, a bit further down is our README with a conflicting wildcard suggestion.

Any objections for just removing the Usage section?

Usage section currently just explains to the user how to add the dependency and adding a extern crate.

How about dropping the Usage section and instead add a badge linking to crates.io on top of readme?

crates.io

[![crates.io](https://img.shields.io/crates/v/image.svg)](https://crates.io/crates/image)

That seems possible. crates.io has a copy & paste section that is sufficient. That badge would always link to the newest version, I'm not sure if this has the intended meaning.

Showing the latest version in the badge was intended.

I imagine a user somewhat familiar with cargo dependencies noting the number and adding a line to their Cargo.toml, rather than us (forgetting?) updating the README after new releases.

Was this page helpful?
0 / 5 - 0 ratings

Related issues

franleplant picture franleplant  ·  3Comments

theotherphil picture theotherphil  ·  3Comments

usagi picture usagi  ·  8Comments

aschampion picture aschampion  ·  3Comments

kolen picture kolen  ·  7Comments