Providers should have a lint workflow/step on the docs folder content

[ringods]

When a resource provider package contains a docs folder, the content should be linted. This workflow/step should pass before a release can happen.

When the content is not correct, these files are copied over to the registry for publishing and it fails the publishing there without any feedback loop back to the source.

Example: MongoDB Atlas is currently at v3.20.1. All versions from v3.18.1 failed publishing so far:

• v3.18.1: Publish Package Metadata mongodbatlas@v3.18.1 registry#5463
• v3.19.0: Publish Package Metadata mongodbatlas@v3.19.0 registry#5489
• v3.19.1: Publish Package Metadata mongodbatlas@v3.19.1 registry#5509
• v3.20.0: Publish Package Metadata mongodbatlas@v3.20.0 registry#5639
• v3.20.1: Publish Package Metadata mongodbatlas@v3.20.1 registry#5665

[ringods]

More cases:

• Publish Package Metadata signalfx@v7.2.2 registry#5620
• Publish Package Metadata civo@v2.4.4 registry#5374

[guineveresaenger]

Thank you for alerting us here, @ringods.

I've gone over open registry PRs and this is currently affecting only the three providers you listed.

The configured markdownlint options can be found in the registry here.

Summary of linting rules failing:

1. Multiple top-level headings in the same document MD025

• Signalfx: inherited from upstream here

2. Ordered list item prefix MD029

• Mongodbatlas: the upstream file does not indent the text between list item numbers, resulting in each numbered list item being interpreted as the first item in a new list.

3. Spaces inside code span elements MD038 - it looks like this: this span has a leading space. It presents on the level of a typo but as the rule documentation says, backtick renders get complicated quickly.

• Mongodbatlas: inherited from upstream here
• Civo: - inherited from upstream here

It seems to me at first glance that these particular linting rules are currently too strict for the _index.md file, for two reasons:

• they do not result in terribly mis-rendered pages on our end (see screenshot of local render, below)
• they render decently on upstream registry; upstream providers do have markdownlinting rules for their docs. Example: https://github.com/newrelic/terraform-provider-newrelic/blob/main/.markdownlinkcheck.json

There's a few options:

1. Fix up linting errors in affected providers. Ideally, as this issue suggests, this would be discovered at pull request time via provider-specific linting step. The drawback is that the main way to fix something like this is via docEditRules which are manual, and a large hammer. Maintenance becomes difficult as well, as these rules depend on detecting incoming text. When that text changes, the rule must be adjusted, or it will quietly cease to do anything. It is possible to add a hard error to assist in detecting upstream changes; this adds potential future maintenance burden.
2. Exclude _index.md files from linting rules in the registry entirely. The drawback here is that we might not catch new and exciting render failures before they go live.
   It is also unclear to me at this point whether we enforce linting on third-party providers. Since maintainers of those providers probably will have an easier time noticing a registry publish failure, we may want to keep the linting rules, or perhaps downgrade them to a warning.
3. Loosen the above three linting rules in the registry. This would apply to a large amount of internal makdown files however.
4. Loosen the above linting rules for only _index.md files. We'd keep strict linting on all other files, and can decide that we're OK with the above issues.

I'm leaning towards a mix of 4 and 1:

• Adjust the above three rules to be unenforced on _index.md files in the registry -> result: publish succeeds even if there's minor lint errors
• Add these adjusted rules to a provider level lint step. When they fail, we either need to fix the file, or decide if we need to adjust the rules further.

Screenshot of local render