Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[BuildCheck]: Guide of rules/analyzers id name #10088

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

f-alizada
Copy link
Contributor

Fixes #9823

Context

Provide the document describing the guidence on the rule id and analyzers name built in and custom ones.

Formatted view: https://github.com/f-alizada/msbuild/blob/f-alizada/dev/design-for-rules-id/documentation/specs/proposed/BuildCheck-Rules-Identification.md

The PR does not introduce the actual implementation. The implementation and changes will be made once this PR is merged (meaning all comments are addressed)

Copy link
Member

@JanKrivanek JanKrivanek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I love the writing - thanks for putting this together!

Not yet approving - as there will be probably some followup discussions... but I feel pretty good about the proposal!


### Problems to address:
- The report should unambiguously point to the rule.
- Errors and execution time reporting for analyzers.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering whether the term 'error' might confuse anyone here (as we use term error as well for the type of finding). How about "Execution and configuration issues and execution time reporting for analyzers"?

### Problems to address:
- The report should unambiguously point to the rule.
- Errors and execution time reporting for analyzers.
- Preventing clashes of identification within a single build: Clashes with well-known rules/analyzers.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Preventing clashes of identification within a single build: Clashes with well-known rules/analyzers.
- Preventing clashes of identification within a single build and clashes of custom rules/analyzers with well-known rules/analyzers.

We basically want to prevent 2 things:

  • a community analyzer/rule producing reports that can be confused with the reports from official MSFT analyzers
  • some community analyzers having same id's and those being loaded into the build produces report that uses identification, while that identification cannot be unambiguously linked to the analyzer package.

To prevent first case - we reserve prefix for ourselves. Thus it cannot be used in any analyzer in any build
To prevent second case - we need to control clashes on the level of the individual builds - as we do not have mechanism for producers to reserve their own prefixes

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for pointing!
The section "Rules Identification clash prevention" is added to the document.

Any build check related configuration should start with the `build_check.` prefix. Without the prefix, the BuildCheck infrastructure will not recognize the input config as a valid key-value, and the config will not be respected.

- Built-in BuildCheck rule configuration
- `build_check.BuildCheck.SharedOutputPath.BC0001.enabled = true|false`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"build_check.BuildCheck..." - feels like duplication. "build_check.Microsoft...." might be more expressive here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree it feels like it.
What do you think about the "msbuild_analyzer.BuildCheck.AnalyzerName ... " where msbuild_analyzer is a required prefix to be respected by infra?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional option:
To leave the build_check as a infra-key, but reserve the MSBuild as a reserved prefix for built-in analyzers.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think

build_check.MSBuild.SharedOutputPath.enabled = true

makes sense to me

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with Rainer here - having the build_check 'namespace' is a good thing (see how language or ecosystem prefixes are used to scope rules for other systems), I just worry a bit about verbosity here. I'd want ideally no more than say 4 segments. <namespace>.<analyzer_id>.<rule_id>.<setting> = <value>.

- Name: `BuildCheck.SharedOutputPath`
- RuleId: `BC0101` or `BC.AdditionalInfo0101` or `BC.Prefix.Test0123`

### Custom analyzers
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wild idea - do we want to allow prefixes for the custom analyzer rules as well? And then being able to refer to that prefix in order to configure the rules by group - e.g.:

FancyBuildChecks.SharedOutputPath.enabled = false
FancyBuildChecks.*.enabled = true

But I haven't thought about that too deeply :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this idea, but my worry here is when two third party analyzers use the same prefix. The same problem that we would have with the rule IDs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The idea is interesting, however the document presents the idea of having less flexibility at early stages of the development.
On later stages we could work on providing more flexibility into configuraition, naming.
Having the configuration based on the prefix is something that I would leave for the future, if agreed across team.
Open to the discussion

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FancyBuildChecks.*.enabled = true

This is dangerous, because listing by wildcard means new rules can get enabled/fail your build by nonobvious upgrades. Less dangerous for package-delivered ones since those should require an explicit upgrade gesture.

...
```

### Categorization
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is something where I'd be curious about wider feedback. I'm not sure if personally I'd prefer groupping by categories (accross all rules) or rather by producers (package names)
But probably - if authors can choose their categorization identifiaction freely - both effects can be eachieved?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The categorization of the analyzers (all possible categories) will be presented by the MSBuild team. This means that it will be represented as enum values, and the identification of the categorization will be maintained by the MSBuild team.

Could you please point out the scenario that you are thinking about which is not very conveniently configurable from the document? (Possibly I'm missing something.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was trying to come up with reasonable set of Categories for the intial list of analyzers (except usage, style), however I believe having only one Category is not sufficient to actually show what the analyzer is about.
Attaching multiple catogories (labeling) possibly could help here, but was not thinking of adding it in the v1.
What do you think about not introducing the Categorization in the v1 of BuildCheck?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like categories in general, because of the "I turned on 'all style checks' and then changed to a new compiler and am now mad because there are new style warnings" case. I support dropping them from v1.

...
```

### Categorization
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The categories section feels a little bit out of place right now. I had a bit of trouble understanding how it fit with the analyzer identification topic. I think expanding it a bit would be nice.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left comment regarding the same topic: #10088 (comment)

- Name: `BuildCheck.SharedOutputPath`
- RuleId: `BC0101` or `BC.AdditionalInfo0101` or `BC.Prefix.Test0123`

### Custom analyzers
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this idea, but my worry here is when two third party analyzers use the same prefix. The same problem that we would have with the rule IDs.


The MSBuild team is currently working on delivering the MSBuild analyzers (aka BuildCheck). The BuildCheck infrastructure has built-in analyzers and functionality to support custom ones. Hence, we need to make sure it will be possible to configure and differentiate built-in and custom analyzers.

Note: Single analyzer can have multiple rules.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe say "method" or "assembly" or "class" or something?

Note: Single analyzer can have multiple rules.

### Problems to address:
- The report should unambiguously point to the rule.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd strongly recommend using the RFC 2119 language:

Suggested change
- The report should unambiguously point to the rule.
- The report must unambiguously identify the rule.


### Problems to address:
- The report should unambiguously point to the rule.
- Execution and configuration issues and execution time reporting for analyzers.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean something like this, or something else?

Suggested change
- Execution and configuration issues and execution time reporting for analyzers.
- Execution and configuration issues and execution time reporting must be attributable to analyzers.

Comment on lines +18 to +22
Every built-in analyzer will have the friendly name: `BuildCheck.{FriendlyName}`.
- Regular expression for the name: `^BuildCheck.[A-Z]{1,}[a-zA-Z0-9_]{0,}$`

Each Rule that is shipped inbox will contain the RuleId as an identifier of the rule for this analyzer.
- The rule id format is as follows: `^BC[A-Za-z_.]{0,}[0-9]{1,}$`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd appreciate more reasoning and description of the concepts "friendly name" and "RuleId".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Btw. do we need a more strict and opinionated guidance on form and especially length of the ids?

@YuliiaKovalova - can you point us to contacts for VS Error Window? - as that team might have some pre-existing guidances

- Name: `BuildCheck.SharedOutputPath`
- RuleId: `BC0101` or `BC.AdditionalInfo0101` or `BC.Prefix.Test0123`

### Custom analyzers
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FancyBuildChecks.*.enabled = true

This is dangerous, because listing by wildcard means new rules can get enabled/fail your build by nonobvious upgrades. Less dangerous for package-delivered ones since those should require an explicit upgrade gesture.

If custom analyzer will not meet predefined pattern the registration of the custom analyzer will fail.

#### Custom VS Custom
The prevention of having the same analyzer/rule's name/id's between custom analyzers is not guaranteed, and during the registration of the custom analyzer, an additional check will happen to ensure that the analyzer name is not already registered.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the only recourse here to drop one or the other? No remap capability in the engine (I don't think there should be! but we should be clear)

Any build check related configuration should start with the `build_check.` prefix. Without the prefix, the BuildCheck infrastructure will not recognize the input config as a valid key-value, and the config will not be respected.

- Built-in BuildCheck rule configuration
- `build_check.BuildCheck.SharedOutputPath.BC0001.enabled = true|false`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think

build_check.MSBuild.SharedOutputPath.enabled = true

makes sense to me

Comment on lines +86 to +87
- `build_check.SharedOutputPath.ID0001.enabled = true|false`
- `build_check.SharedOutputPath.ID0001.severity = Error`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find using SharedOutputPath as your example custom rule a bit confusing, can you make that more distinct? CustomThirdParty or something?

Comment on lines +122 to +123
- Rule
- Analyzer
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Elaborate on this please?

```
root=true

[FooBar.csproj]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did we discuss this in the .editorconfig meeting? Do we generally expect people to configure per-project by adding a project-folder .editorconfig or by adding a section like this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It shouldn't matter - due to the hierarchical nature and the fact that even in a co-located .editorconfig the user would still need the [FooBar.csproj] section header. So you can organize in a single file with N project sections, or N files with 1 project section, or any combination thereof.

@JanKrivanek JanKrivanek requested a review from baronfel May 9, 2024 14:07
Any build check related configuration should start with the `build_check.` prefix. Without the prefix, the BuildCheck infrastructure will not recognize the input config as a valid key-value, and the config will not be respected.

- Built-in BuildCheck rule configuration
- `build_check.BuildCheck.SharedOutputPath.BC0001.enabled = true|false`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with Rainer here - having the build_check 'namespace' is a good thing (see how language or ecosystem prefixes are used to scope rules for other systems), I just worry a bit about verbosity here. I'd want ideally no more than say 4 segments. <namespace>.<analyzer_id>.<rule_id>.<setting> = <value>.

```
root=true

[FooBar.csproj]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It shouldn't matter - due to the hierarchical nature and the fact that even in a co-located .editorconfig the user would still need the [FooBar.csproj] section header. So you can organize in a single file with N project sections, or N files with 1 project section, or any combination thereof.

- Name: `BuildCheck.SharedOutputPath`
- RuleId: `BC0101` or `BC.AdditionalInfo0101` or `BC.Prefix.Test0123`

### Custom analyzers
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is the naming difference between built-in and custom checks coming from? As far as I know Roslyn doesn't have a similar concept here.

@f-alizada f-alizada changed the title The document to provide guide of rules/analyzers id name [BuildCheck]: Guide of rules/analyzers id name May 17, 2024
@JanKrivanek JanKrivanek mentioned this pull request Jun 17, 2024
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Research and implement rules/analyzers identification and filtering strategy
5 participants