add explanations for several of the added tests

Author: Skgland

tests/buildtest/crates/invalid-cargotoml-conflicting-links/Cargo.toml

@@ -14,3 +14,15 @@ ring_14 = { version = "=0.14.6", package = "ring" }
 [replace]
 "ring:0.13.5" = { git = "https://github.com/briansmith/ring.git", rev = "704e4216a397bd830479bcd6d7dd67fc62cdbe67" }
 "ring:0.14.6" = { git = "https://github.com/briansmith/ring.git", rev = "ef85df478152aa3fe06c811309379efa08f8a529" }
+
+
+# Both of the above packages declare the package.links ¹ key with value "ring-asm" in their respective Cargo.toml ² ³ file.
+# As each links value may only be used by one package in the dependency tree depending on both causes a conflict and cargo fill fail.
+#
+# [INFO] [stderr]     Updating crates.io index
+# [INFO] [stderr] error: Attempting to resolve a dependency with more than one crate with links=ring-asm.
+# [INFO] [stderr] This will not build as is. Consider rebuilding the .lock file.
+# 
+# [1]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-links-field
+# [2]: https://github.com/briansmith/ring/blob/704e4216a397bd830479bcd6d7dd67fc62cdbe67/Cargo.toml#L15
+# [3]: https://github.com/briansmith/ring/blob/ef85df478152aa3fe06c811309379efa08f8a529/Cargo.toml#L16

tests/buildtest/crates/invalid-cargotoml-content-deps/Cargo.toml

@@ -10,3 +10,17 @@ edition = "2018"
 parity-db = "=0.2.3"
 # invalid package name in invalid-cargotoml-content is too invalid
 # invalid-cargotoml-content = { git = "https://github.com/rust-lang/rustwide.git", rev = "ee102383cbe40aafdfce7bf04a120226c16a8983" }
+
+# parity-db version 0.2.3 specifies a dependency on parking_lot at version "0.11\t" in its Cargo.toml ¹ file, but a tab character is not
+# allowed in the package version constraint causing cargo to error out.
+#
+#  Downloaded parity-db v0.2.3
+# error: failed to parse manifest at `/workspace/cargo-home/registry/src/index.crates.io-1949cf8c6b5b557f/parity-db-0.2.3/Cargo.toml`
+#
+# Caused by:
+#   failed to parse the version requirement `0.11	` for dependency `parking_lot`
+#
+# Caused by:
+#   expected comma after minor version number, found '\t'
+#
+# [1]: https://docs.rs/crate/parity-db/0.2.3/source/Cargo.toml.orig#13

tests/buildtest/crates/invalid-cargotoml-content-type-in-deps/Cargo.toml

@@ -8,3 +8,19 @@ edition = "2018"
 
 [dependencies]
 libressl-pnacl-sys = "=2.1.0"
+
+# libressl-pnacl-sys at version 2.1.0 specifies in its Cargo.toml ¹ file a key `[[lib]]` (an array of tables),
+# but the lib key is supposed to be a table ('[lib]'). As such cargo considerse the Cargo.toml to be invalid and fails to compile the crate.
+#
+#   Downloaded libressl-pnacl-sys v2.1.0
+# error: invalid type: map, expected a string
+#   --> ../../../cargo-home/registry/src/index.crates.io-1949cf8c6b5b557f/libressl-pnacl-sys-2.1.0/Cargo.toml:10:1
+#    |
+# 10 | / [[lib]]
+# 11 | | name = "cross-platform-ssl-link"
+# 12 | | path = "lib.rs"
+#    | |_______________^
+#    |
+# 
+# [1]: The Cargo.toml.orig can be found in the .crate archive available at https://static.crates.io/crates/libressl-pnacl-sys/libressl-pnacl-sys-2.1.0.crate
+#

tests/buildtest/crates/invalid-cargotoml-missing-override/Cargo.toml

@@ -11,3 +11,8 @@ build-rs = "=0.1.2"
 
 [replace]
 "build-rs:0.1.2" = { git = "https://github.com/rust-lang/rustwide.git", rev = "07784be00b68cfd6bf80006c8d8669a7d6374ec2" }
+
+# Note that the rustwide repository at the specified revision does not declare a package of the name `build-rs`
+# as such the declared replacement of the build-rs crate cannot be applied and cargo fails.
+#
+# This is a reproduction for crater errors like https://crater-reports.s3.amazonaws.com/beta-1.86-1/1.85.0/gh/bestform.game-of-life.rs/log.txt

tests/buildtest/crates/invalid-cargotoml-missing-patch/Cargo.toml

@@ -11,3 +11,9 @@ build-rs = "=0.1.2"
 
 [patch.crates-io]
 build-rs = { git = "https://github.com/rust-lang/rustwide.git", rev = "07784be00b68cfd6bf80006c8d8669a7d6374ec2" }
+
+
+# Note that the rustwide repository at the specified revision does not declare a package of the name `build-rs`
+# as such the declared patch of the build-rs crate cannot be applied and cargo fails.
+#
+# This is a reproduction for crater errors like https://crater-reports.s3.amazonaws.com/beta-1.86-1/1.85.0/gh/mrvillage.timer/log.txt

tests/buildtest/crates/invalid-cargotoml-missing-registry-config/Cargo.toml

@@ -8,3 +8,9 @@ edition = "2018"
 
 [dependencies]
 build-rs = { version = "*", registry = "will-be-removed" }
+
+# During the preperation rustwide will remove the ./.config/config.toml file
+# this will make the build-rs dependecy refere to an undefined registry
+# which causes cargo to fail.
+#
+# This is a reproduction for crater errors like https://crater-reports.s3.amazonaws.com/beta-1.86-1/1.85.0/gh/retrokiller543.rust-echo/log.txt

tests/buildtest/crates/invalid-cargotoml-syntax-deps/Cargo.toml

@@ -8,3 +8,14 @@ edition = "2018"
 
 [dependencies]
 url = "=0.5.9"
+
+# The url dependency at version 0.5.9 was published with a malformed Cargo.toml, this syntax error causes cargo to fail.
+#
+# [INFO] [stderr]  Downloading crates ...
+# [INFO] [stderr] error: invalid table header
+# [INFO] [stderr] expected newline, `#`
+# [INFO] [stderr]   --> ../../../cargo-home/registry/src/index.crates.io-1949cf8c6b5b557f/url-0.5.9/Cargo.toml:14:10
+# [INFO] [stderr]    |
+# [INFO] [stderr] 14 | [[test]] name = "format"
+# [INFO] [stderr]    |          ^
+# [INFO] [stderr]    |

tests/buildtest/crates/lockfile-collision/Cargo.toml

@@ -8,3 +8,11 @@ edition = "2018"
 
 [dependencies]
 lockfile-collision = { path = "./crates/lockfile-collision" }
+
+# Note that this package and its dependency have the same name
+# this results in Cargo being unable to build a lock file as both packages would have the same entry key.
+#
+# This is a reproduction for crater errors like https://crater-reports.s3.amazonaws.com/beta-1.86-1/1.85.0/gh/shadowmint.loghaul/log.txt
+#
+# [INFO] [stderr]     Blocking waiting for file lock on package cache
+# [INFO] [stderr] error: package collision in the lockfile: packages loghaul v0.1.0 (/workspace/builds/worker-3-tc2/source) and loghaul v0.1.0 (/workspace/builds/worker-3-tc2/source/crates/loghaul) are different, but only one can be written to lockfile unambiguously

tests/buildtest/crates/missing-deps-registry-version/Cargo.toml

@@ -8,3 +8,10 @@ edition = "2018"
 
 [dependencies]
 empty-library = "=0.5.0"
+
+# Note that while the crate empty-library is published to crates.io it does not have a version 0.5.0 published ¹
+# as such cargo will fail as it will be unable to find a matching package version for the specified dependency
+#
+# This is a reproduction for crater errors like https://crater-reports.s3.amazonaws.com/beta-1.86-1/1.85.0/gh/adelelopez.bayes/log.txt
+#
+# [1]: https://crates.io/crates/empty-library/versions