(this concerns contribution -documentation- issue)
As far as I can tell, the new docs\Rules\README.md setup (PR2196) will cause a merge conflict with every new rule added to the analyzer repo like: #2186 and #2183.
The new format change:
- Update rules index (docs/Rules/README.md) to a new “Default state” model and add link references for maintainability
Which results in a table like:
| Rule | Severity | Default state | Configurable |
| -------------------------------------------------- | ----------- | :------------: | :----------: |
| [AlignAssignmentStatement][02] | Warning | Disabled | Yes |
| [AvoidAssignmentToAutomaticVariable][03] | Warning | Always enabled | |
| [AvoidDefaultValueForMandatoryParameter][04] | Warning | Always enabled | |
...
And a reference list like:
<!-- link references -->
[01]: ../using-scriptanalyzer.md#suppressing-rules
[02]: AlignAssignmentStatement.md
[03]: AvoidAssignmentToAutomaticVariable.md
[04]: AvoidDefaultValueForMandatoryParameter.md
[05]: AvoidDefaultValueSwitchParameter.md
...
Might a beter practice for a static README.md, it isn't for a dynamic README.md that needs to be updated with each new rule. The difficulty is because the rule list is alphabetically and inserting a new rule document to the list requires to update all following rules and reference links (that are not related to the new rule PR). Doing so, is in fact rather difficult to maintain and error prone.
A workaround might simply using the next available reference number (e.g. [81]) but that would then appear somewhere in the middle of the list (depending on the rule name) with is quite inconsistent and doesn't add much value to the "maintainability".
(this concerns contribution -documentation- issue)
As far as I can tell, the new
docs\Rules\README.mdsetup (PR2196) will cause a merge conflict with every new rule added to the analyzer repo like: #2186 and #2183.The new format change:
Which results in a table like:
And a reference list like:
Might a beter practice for a static
README.md, it isn't for a dynamicREADME.mdthat needs to be updated with each new rule. The difficulty is because the rule list is alphabetically and inserting a new rule document to the list requires to update all following rules and reference links (that are not related to the new rule PR). Doing so, is in fact rather difficult to maintain and error prone.A workaround might simply using the next available reference number (e.g.
[81]) but that would then appear somewhere in the middle of the list (depending on the rule name) with is quite inconsistent and doesn't add much value to the "maintainability".