license-file without license seems ill-advised

[cuviper]

Problem

If you include both license and license-file in Cargo.toml, you get a warning:

cargo/src/cargo/util/toml/mod.rs

Lines 1311 to 1317 in aa68721

	if project.license_file.is_some() && project.license.is_some() {
	manifest.warnings_mut().add_warning(
	"only one of `license` or \
	`license-file` is necessary"
	.to_string(),
	);
	}

However, crates.io doesn't know how to describe an arbitrary license-file, so it ends up being called "non-standard", which is rather poor for the user. Maybe this could be considered a crates.io issue, but I don't think they should be expected to guess what the SPDX license is from a file. When multiple files are supported (#5933), it really can't know whether that should be AND or OR.

For example, see the difference between pretty-git-prompt 0.2.0 and 0.2.1, which dropped the license field on cargo's recommendation.

Steps

1. Add both license and license-file
2. $ cargo package
warning: only one of `license` or `license-file` is necessary
3. If published with just license-file, crates.io calls the license "non-standard".

Possible Solution(s)

I think maybe it should be a warning if only license-file is present, since license is better for providing SPDX to show on crates.io.

Notes

Output of cargo version:

cargo 1.46.0-nightly (43cf77395 2020-07-13)

And that warning is still on master as of aa68721, as linked above.

cc tokio-rs/tracing#842

[cuviper]

It looks like the "nonstandard" aspect was always known -- #974:

This key will support projects with nonstandard licenses and the registry will
display the license as "nonstandard".

But there are good reasons to want license-file even when it is some standard SPDX, like including the file in the package from outside the crate directory (#7905).

[ehuss]

Perhaps I'm misunderstanding the circumstance, but if a project is using a standard SPDX license, then it should fill in the license field. If it has a non-standard license, it should fill in the license-file field. It is not unusual for projects to use non-standard licenses, so I'm not sure a warning is warranted.

Is the concern that someone will fill out the license-file when they should have filled in the license field because they are using a standard license? The documentation does try to make the distinction clear, but maybe it is not clear enough?

I think the warning about setting both could definitely be clarified about which to use.

[cuviper]

Is the concern that someone will fill out the license-file when they should have filled in the license field because they are using a standard license? The documentation does try to make the distinction clear, but maybe it is not clear enough?

Yes, this. I didn't know license-file was only intended for non-standard licenses, but I'll admit I hadn't looked closely at those docs to realize that was significant.

I think the warning about setting both could definitely be clarified about which to use.

Yes, I think that would help.

However, I do think it's useful to have license-file even for standard licenses, because many of those licenses are supposed to be distributed along with the source. We run into this a lot with distro packaging, since our review process includes checks for license compliance, and a lot of published crates are missing license files. Sometimes folks just don't have it in the repo at all, but often this happens with workspace crates where the license is only in the repo root, so it doesn't get added to the crate package. We end up asking them to either copy the file to every sub-crate or at least symlink it, but links don't play nice on Windows. It would be nice to just use license-file = "../LICENSE" to get it in the package, without calling this "non-standard".

[joshtriplett]

Right now, license and license-file are intentionally somewhat mutually exclusive, because license-file doesn't provide any semantics for how the license is used. If you write license = "MIT", license-file = "LICENSE.txt", that could have several semantic meanings. Does that mean that LICENSE.txt is just the project's version of an MIT license (perhaps with a project-specific copyright notice)? Or is this a dual-license, between MIT and a custom license (MIT OR Custom)? Or is it two licenses that both apply, such that part of the project is under MIT and part is under a custom license (MIT AND Custom)?

We talked about this in today's @rust-lang/cargo meeting. We agreed that we don't want Cargo to take on the responsibility of innovating in the area of software license specification. Instead, we'd prefer to delegate this to some existing standard.

So, a few concrete proposals:

• I think in general that tools built atop Cargo should be responsible for complex operations like "collect all relevant license texts", using a combination of Cargo metadata and metadata from other standards such as SPDX, REUSE, or Debian's DEP-5. Such tools can have heuristics like "the license expression specifies MIT, and there's also a LICENSE file, but the LICENSE file is just MIT plus a copyright notice at the top, so let's capture that LICENSE file and not a duplicate copy of the MIT license".
• I think one or more of the authors of such tools should work with SPDX to seek an extension to the SPDX license expression syntax to add tokens like Custom:xyz or MIT:my-copy-of-the-MIT-license. Given an appropriate extension syntax there, the Cargo team wouldn't have any objections to integrating that syntax into license, and potentially add a separate license-files to provide the key-value mappings like "xyz": "some-file.txt" (with reasonable defaults for license filenames). license-file could become a special case of license-files.
• Any complexity beyond "this whole crate has this SPDX license expression with these custom tokens" doesn't belong in Cargo at all. For instance, the REUSE and DEP-5 specifications support specifying license information that applies to a subset of files in a project. Cargo's metadata should stick to crate-level granularity.

Based on all of that, we're going to close this issue for now. We care about seeing this solved, but we'd like to see an appropriate extension to SPDX expressions such that the expression in license can reference the license files either by filename or by token mapped via some other cargo metadata. We'd be happy to see folks return with a PR when there's something appropriate like that for the PR to implement..

[cuviper]

@joshtriplett can we at least clarify the warning as @ehuss suggested?

I think the warning about setting both could definitely be clarified about which to use.

[joshtriplett]

@cuviper Sure, I think clarifying that message would be reasonable.

[ehuss]

I went ahead and posted #9941 to add some detail to the warning message.

[sparr]

I want to specify license so that crates.io knows what license I am using, and various other tools can categorize my crate appropriately without needing to parse my license file.

I want to specify license-file because my standard license contains one unique line, just like almost every other license file, the one with the copyright date and my name. It's important that people and tools know where to find that file and info.

As things stand now, the manifest spec gives us no way to say "I'm using a standard license, and it's in this file" which would be useful to avoid having to guess whether it's going to be in LICENSE or license or LICENSE.txt or ... (I just reached semantic satiation on "license"). @joshtriplett's suggestion for a license-files array to map licenses to files would resolve this for me.

[epage]

I want to specify license-file because my standard license contains one unique line, just like almost every other license file, the one with the copyright date and my name. It's important that people and tools know where to find that file and info.

Last I heard from a lawyer, the date isn't needed.

The problem I realized with the name field is that, without copyright assignment, every contributor has a copyright claim on the source code and I was misrepresenting the copyright with just my name.

So for me, that one line doesn't seem like a motivation to act on anything. I imagine we are still in the "wait for prior art / a standard" mode for this.