Azure / Azure/bicep

Provide informative guidance on linter/compiler warnings on use of experimental features

Open
#10,351 0 comments 0 reactions 0 assignees View on GitHub
documentation error-message
Dominant language
Bicep
Stars
3.6k
Forks
830
Avg merge
1d 21m
Merged PRs (30d)
79

Description

**Describe the bug**
At the time of writing, when a user wishes to make use of an experimental feature of Bicep, in case the feature has not been enabled in `bicepconfig.json` the user is presented with a message that is not informative enough. Consider the following example of a user attempting to use the `extensibility providers` feature:

![image](https://user-images.githubusercontent.com/9611108/230683617-e4d4f8f5-565b-4e87-ac7a-b410e9bd8488.png)

Notice how the message is not informing the user how to enable the extensibility feature and what steps to take to make use of this feature. An alternative message that is informative would include:

- How to enable the feature. That is, save the file and create a `bicepconfig.json` with the relevant flags set and a or a link to the documentation about how to do it
- Any disclaimers about the pre-requisites for the feature including how to make use of it in the extension or without the extension

**To Reproduce**
Steps to reproduce the behavior:
1. Create a manifest as described above

**Additional context**
Related to the discussion in - https://github.com/Azure/bicep/issues/9902

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the extensibility providers example with the feature disabled in bicepconfig.json, and review the related discussion in issue 9902. Trace where the linter or compiler warning is produced. Done means the warning explains how to enable the experimental feature, points to relevant documentation when available, and states its prerequisites.

Written by the indexing model from the issue text.

Assessment

Domain
compilers, devtools
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.