From f6f608c2c688d3762dc24406be7a68bd60402457 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Fri, 27 Sep 2024 02:30:08 +0200 Subject: [PATCH 1/3] add `
` to the `CONTRIBUTING.md` to make some content not so in your face --- CONTRIBUTING.md | 76 +++++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c8851f54..2790a78c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -168,8 +168,9 @@ If it didn't fail, then your lint didn't report any semver issues in the test cr and probably isn't working quite right. (Did any other lints' tests fail also? See the [troubleshooting item](#troubleshooting-other-lints-tests-failed-too) below.) -For a lint named `enum_struct_variant_field_added`, you'll probably see its test fail with -a message similar to this: +
For a lint named enum_struct_variant_field_added, you'll probably see its test fail with +a message similar to this + ``` Query enum_struct_variant_field_added produced incorrect output (./src/lints/enum_struct_variant_field_added.ron). @@ -196,6 +197,8 @@ Actual output: } ``` +
+ Inspect the "actual" output: - Does it report the semver issue your lint was supposed to catch? If not, the lint query or the test crates' code may need to be tweaked. @@ -291,51 +294,56 @@ otherwise the test will fail in CI. *TODO: @suaviloquence will write this once the feature has been implemented.* ### Troubleshooting -#### A valid query must output span_filename and/or span_begin_line -If your lint fails with an error similar to the following: -``` ----- query::tests_lints::enum_missing stdout ---- -thread 'query::tests_lints::enum_missing' panicked at 'A valid query must output both `span_filename` and `span_begin_line`. See /~https://github.com/obi1kenobi/cargo-semver-checks/blob/main/CONTRIBUTING.md for how to do this.', src/query.rs:395:26 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace -``` - -It likely means that your lint does not specify the `span_filename` and `span_begin_line` of where the error occurs. To fix this, add the following to the part of query that catches the error: -``` -span_: span @optional { - filename @output - begin_line @output -} -``` - -#### Other lints' tests failed too - -This is not always a problem! In process of testing a lint, it's frequently desirable to include -test code that contains a related semver issue in order to ensure the lint differentiates between -them. -For example, say one is testing a lint for pub field removals from a struct. Its test crate code +-
A valid query must output span_filename and/or span_begin_line + + If your lint fails with an error similar to the following: + ``` + ---- query::tests_lints::enum_missing stdout ---- + thread 'query::tests_lints::enum_missing' panicked at 'A valid query must output both `span_filename` and `span_begin_line`. See /~https://github.com/obi1kenobi/cargo-semver-checks/blob/main/CONTRIBUTING.md for how to do this.', src/query.rs:395:26 + note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace + ``` + + It likely means that your lint does not specify the `span_filename` and `span_begin_line` of where the error occurs. To fix this, add the following to the part of query that catches the error: + ``` + span_: span @optional { + filename @output + begin_line @output + } + ``` + +
+-
Other lints' tests failed too + + This is not always a problem! In process of testing a lint, it's frequently desirable to include + test code that contains a related semver issue in order to ensure the lint differentiates between + them. + + For example, say one is testing a lint for pub field removals from a struct. Its test crate code may then include removals of the entire struct, in order to make sure that the lint *does not* report those. But those struct removals *will* get reported by the lint that looks for semver violations due to struct removal! - -So if you added code to a test crate and it caused other lints to report new findings, consider: -- whether your code indeed contains the reported semver issue; -- whether the same semver issue is being reported only once, and not multiple times - by different lints, -- and whether the new reported lint result points to the correct item and span information. - -If the answer to all is yes, then everything is fine! Just edit those other lints' + + So if you added code to a test crate, and it caused other lints to report new findings, consider: + - whether your code indeed contains the reported semver issue; + - whether the same semver issue is being reported only once, and not multiple times + by different lints, + - and whether the new reported lint result points to the correct item and span information. + + If the answer to all is yes, then everything is fine! Just edit those other lints' expected output files to include the new items, and you can get back on track. + +
## Development Environment ### Running required automation scripts -While cargo-semver-checks is cross platform, the development task automation scripts in the scripts +While cargo-semver-checks is cross-platform, the development task automation scripts in the scripts directory require a `bash` shell to run. Windows users can get a bash + GNU command line environment via WSL or git bash. -Linux and Mac OS typically have bash installed by default. +Linux and macOS typically have bash installed by default. ### Language server (LSP) integration From b0e0c43b9615eb0397983562443ce6ca62444e47 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sun, 29 Sep 2024 03:10:09 +0200 Subject: [PATCH 2/3] made the requested changes --- CONTRIBUTING.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2790a78c..c0589818 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -168,9 +168,8 @@ If it didn't fail, then your lint didn't report any semver issues in the test cr and probably isn't working quite right. (Did any other lints' tests fail also? See the [troubleshooting item](#troubleshooting-other-lints-tests-failed-too) below.) -
For a lint named enum_struct_variant_field_added, you'll probably see its test fail with -a message similar to this - +For a lint named `enum_struct_variant_field_added`, you'll probably see its test fail with +a message similar to this: ``` Query enum_struct_variant_field_added produced incorrect output (./src/lints/enum_struct_variant_field_added.ron). @@ -197,8 +196,6 @@ Actual output: } ``` -
- Inspect the "actual" output: - Does it report the semver issue your lint was supposed to catch? If not, the lint query or the test crates' code may need to be tweaked. @@ -295,7 +292,7 @@ otherwise the test will fail in CI. ### Troubleshooting --
A valid query must output span_filename and/or span_begin_line +-
A valid query must output span_filename and/or span_begin_line (click to expand) If your lint fails with an error similar to the following: ``` @@ -313,7 +310,7 @@ otherwise the test will fail in CI. ```
--
Other lints' tests failed too +-
Other lints' tests failed too (click to expand) This is not always a problem! In process of testing a lint, it's frequently desirable to include test code that contains a related semver issue in order to ensure the lint differentiates between From 5eb2022b5923966e67d5af6508e39e4eef116346 Mon Sep 17 00:00:00 2001 From: Predrag Gruevski <2348618+obi1kenobi@users.noreply.github.com> Date: Mon, 30 Sep 2024 14:51:15 -0400 Subject: [PATCH 3/3] Update CONTRIBUTING.md --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0589818..144ba54c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -329,7 +329,6 @@ violations due to struct removal! If the answer to all is yes, then everything is fine! Just edit those other lints' expected output files to include the new items, and you can get back on track. -
## Development Environment