Conventions for Cargo.toml files. #41

Merged
merged 1 commit into from Jan 18, 2017

Projects

None yet

5 participants

@joshtriplett
Member

No description provided.

@solson
solson approved these changes Nov 29, 2016 View changes

LGTM

@killercup

LGTM. As mentioned inline, can you add a link to the version of the TOML spec that corresponds as closely as possible to what Cargo currently understands?

In other news, when we finally have a TOML writer targeting human consumption and as little diff noise as possible, and integrate that into cargo-edit, this is spec is I will be using! 😄

+followed by the `description` at the end of that section.
+
+Don't use quotes around any standard key names; use bare keys. Only use quoted
+keys for non-standard keys whose names require them, and avoid introducing such
@killercup
killercup Nov 29, 2016

whose names require them

Can you specify when that is required or link to TOML spec? Actually: Link to the TOML spec anyway :)

@joshtriplett
joshtriplett Nov 29, 2016 Member

Quoting https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md#table:

Keys may be either bare or quoted. Bare keys may only contain letters, numbers, underscores, and dashes (A-Za-z0-9_-). Quoted keys follow the exact same rules as basic strings and allow you to use a much broader set of key names. Best practice is to use bare keys except when absolutely necessary.

@joshtriplett
Member

@killercup I think that Cargo follows the current version, https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md. Resident Cargo expert @alexcrichton would know for sure.

@alexcrichton
Member

Ah yes Cargo uses toml-rs which follows the TOML spec as closely as it can, so the master version of the TOML spec is what it follows. I forget if that's exactly 0.4.0 or slightly beyond it wrt a few small cases.

@joshtriplett
Member

@alexcrichton Would it make sense, then, to link to the latest version of the spec and update that reference if Cargo/toml-rs ever needs to refer to an older snapshot rather than the latest version?

@alexcrichton
Member

Sure!

@nrc
Collaborator
nrc commented Dec 16, 2016

This LGTM, and I think is ready for FCP

@nrc
nrc approved these changes Dec 16, 2016 View changes
+
+The authors list should consist of strings that each contain an author name
+followed by an email address in angle brackets: `Full Name <email@address>`.
+It should not contain bare email addresses, or names without email addresses.
@nrc
nrc Dec 16, 2016 Collaborator

Is there a case where people might want credit without giving contact info?

@joshtriplett
joshtriplett Dec 18, 2016 Member

That exact case led me to write "should" instead of "must" here.

+followed by an email address in angle brackets: `Full Name <email@address>`.
+It should not contain bare email addresses, or names without email addresses.
+(The authors list may also include a mailing list address without an associated
+name.)
@nrc
nrc Dec 16, 2016 Collaborator

Nit: I think the full stop goes outside the parens, here and below. I bet this is something different style guides disagree on though.

@solson
solson Dec 16, 2016 Member

@nrc The rule I've heard is that when part of sentence, the full stop is outside (like this). (But when the parens enclose an entire sentence, it's inside, like this.)

@joshtriplett
joshtriplett Dec 18, 2016 Member

I've heard the same rule as @solson. In this case, the parenthetical contains a sentence; the sentence doesn't contain a parenthetical.

guide/guide.md
+(The authors list may also include a mailing list address without an associated
+name.)
+
+The license field should contain a valid SPDX expression, using valid SPDX
@nrc
nrc Dec 16, 2016 Collaborator

Could you link to what SPDX is?

guide/guide.md
+The homepage field, if present, should consist of a single URL, including the
+scheme (e.g. `https://example.org/`, not just `example.org`.)
+
+Within the description field, wrap text at 78 columns. Don't start the
@nrc
nrc Dec 16, 2016 Collaborator

Is this 80 cols minus the start and end quote marks? Or 78 including the quote marks?

@joshtriplett
joshtriplett Dec 18, 2016 Member

I intended this as 78 columns of description text, not counting the quote marks.

@nrc
Collaborator
nrc commented Jan 18, 2017

This has been in FCP for about a month, and module some haggling about grammar nits has no significant comments, so I'm merging it.

@nrc nrc merged commit abfab15 into rust-lang-nursery:master Jan 18, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment