The new `docs\Rules\README.md` format causes merge issues

Ouverte
#2,220 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

@HuffmanStacks y travaille déjà.

Depuis le 8/11/2026.

  • #2301 par @HuffmanStacks — ouverte

Évaluation

Difficulté
3/5
Temps estimé
1-2 jours
Accessibilité débutants
48/100
Type d'issue
Documentation
Clarté
Plutôt claire
Activité
Active
Stack technique
markdown
Domaine
documentation

Piste de recherche

Start with docs/Rules/README.md and compare the format introduced by PR2196 with the conflicts reported in PRs #2186 and #2183. Determine a maintainable reference or index arrangement; done means adding an alphabetized rule does not require renumbering unrelated entries or create merge conflicts.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

(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 be 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".

Langage dominant
C#
Étoiles
2.2k
Forks
422
Merge moyen
2 h 23 min
PR mergées (30 j)
25

Préparer son environnement

Ouvrir dans Codespaces

Lance le conteneur de développement du projet dans votre navigateur, avec votre propre compte GitHub.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de PowerShell/PSScriptAnalyzer

Toutes les issues de PowerShell/PSScriptAnalyzer

Issues similaires

Plus d'issues C#

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.