Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Aberta
  • Algo errado?
#2,220 0 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
48/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
markdown
Domínio
documentation

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

(this concerns contribution -documentation- issue)

As far as I can tell, the new docs\Rules\README.md setup (PR2196) will cause an 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, 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".

Linguagem predominante
C#
Estrelas
2.2k
Forks
415
Merge médio
13h 1min
PRs com merge (30d)
2

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de PowerShell/PSScriptAnalyzer

Todas as issues de PowerShell/PSScriptAnalyzer

Issues semelhantes

Mais issues de C#

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.