Proposal - Simplification of "built-in" vs "registry-supplied" providers
- Dominant language
- Bicep
- Stars
- 3.6k
- Forks
- 830
- Avg merge
- 1d 21m
- Merged PRs (30d)
- 79
Description
## Problem Statement
With the work to make az types consumable via registry (#5453), we're introducing the following syntax:
```bicep
import 'br/public:az@0.2.3'
```
We also currently support the following syntax for "built-in" providers:
```bicep
import 'sys@1.0.0'
```
Both syntaxes also support aliasing:
```bicep
import 'br/public:az@0.2.3' as myAz
import 'sys@1.0.0' as mySys
```
I foresee the following problems:
* The new syntax is quite verbose, and cannot be controlled centrally. For users with a large set of files, picking up the latest version of `az` will require modifying every single file.
* The aliasing (assuming that the last segment of the registry namespace == the provider name) & versioning (having an `@` character instead of a `:` which is familiar to module users) behavior of the new syntax is potentially confusing.
* It feels deceiving and confusing to say that `sys` is fixed version `1.0.0` - this **should** imply that there are no changes between Bicep versions, which isn't realistic.
* It's an "either/or" - either users follow the current behavior (`az` imported by default) **or** they're using the new syntax. We don't have a plan for how to combine the two.
* With [Radius](https://github.com/radius-project/radius), it's conceivable that we may want users to **not** have `az` imported by default.
## Possible Solution
Add a section to `bicepconfig.json` (exact structure TBD, this is just a mockup to introduce the concept):
```json
{
"providers": {
"az": {
"source": {
"registry": "mcr.microsoft.com/bicep/providers/az",
"version": "0.2.3",
},
"isDefaultImport": true
},
"sys": {
"source": {
"builtin": true
},
"isDefaultImport": true
}
}
}
```
Support a simpler syntax for provider imports if there is configuration:
```bicep
import az
import sys
```
Remove support for the current built-in syntax:
```bicep
import 'sys@1.0.0'
```
Continue to support the new registry-supplied syntax, but have it more aligned with the module syntax:
```bicep
import 'br:mcr.microsoft.com/bicep/providers/az:0.2.3'
```
### Benefits
* Because each release of Bicep embeds a default `bicepconfig.json`, we can use this to preserve the existing behavior of fixing a given release of Bicep to a fixed set of types.
* Simple and well-defined path for users to override this behavior via the existing mechanisms for `bicepconfig.json`.
* Addresses the problems called out in the "problem statement" section.
## Open Questions
* Should we assume a version for "sys" even though it's not registry-driven?
* Should the "types.json" spec contain metadata about modules (e.g. [this information](https://github.com/Azure/bicep/blob/4137eccae0b52248fe8369ad91d81d688f89eb38/src/Bicep.Core/Semantics/Namespaces/SystemNamespaceType.cs#L46-L51))?
## Other Notes
* An important goal for this proposal is that the behavior for existing Bicep users (those without any `import` statements) is not modified - so we continue to assume that `az` and `sys` are both imported by default.
Also wanted to credit @shenglol for helping me think this through 😄
Contributor guide
Research direction
Start by reviewing the proposed bicepconfig.json provider section, the import examples, and the referenced types.json metadata question. Resolve the open design questions and define the configuration and import behavior, including how existing users retain the default az and sys imports.
Written by the indexing model from the issue text.
Assessment
- Domain
- compilers
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100