Print a warning if anything other than Markdown or plain text is specified in the `readme` field

[sorairolake]

Problem

crates.io interprets the package's README file specified in the readme field as Markdown.¹ This file can accept a non-Markdown file such as README.rst (reStructuredText) or README.adoc (AsciiDoc). However, these are not Markdown file and therefore will not render as expected. This behavior can be known by looking at https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-readme-field or the crate's page after it is released. However, when we run a command such as cargo publish, no warnings or errors are printed, so we cannot know this behavior at that time.

Proposed Solution

If a the extension of the specified path does not match any of .md, .txt or no extension, print a warning when executing a command such as cargo publish.

I think printing a warning is printed indicating that the readme field is expecting a Markdown file would reduce the chance of accidentally specifying the README file in a different format.

I think in most projects the README file is a Markdown file named README.md. Also, I think many projects omit this field and use the default value. So I think this problem is unlikely to occur, but I think it would be useful if a warning was printed, since there may be cases where the README file other than README.md are stored.

Notes

There seem to be other extensions for Markdown, such as .markdown, but I'm not sure if they should be supported.

This might be better detected by the clippy.

Footnotes

1. https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-readme-field ↩

[weihanglo]

Thanks for the proposal!

This might be better detected by the clippy.

Not exactly. Clippy team has expressed that Cargo-related lint should be in Cargo rather than in Clippy (See #t-cargo > Cargo Lints @ 💬).

If a the extension of the specified path does not match any of .md, .txt or no extension, print a warning when executing a command such as cargo publish.

Detecting extension may have some false-positive. In the wild some README files are extension-less. The approach here might not meet the bar of a warn-by-default lint. .txt also doesn't mean it is a markdown file.

The other important thing worth mentioning: crates.io is a registry known to parse package.readme as markdown, but there are other alternative registries that don't. If we decided to warn that, that should be restricted to crates.io only.

[weihanglo]

Other alternative would like try parsing it as markdown, and warn if fail to parse. Downside: Cargo got a hard-dependency on a markdown parser.