BBurns meeting notes 7/23/2020

[majastrz]

Parameter, variables and outputs

• Brendan really liked separating the export from the variable assignments as a way to separate contract from the implementation. The syntax would be something like the following:

// contract section
parameter foo string
export bar string

...
...
...

// somewhere in the middle of the file
var bar = <expression>

...
...
...
...

• The types on exports could be optional but not a strong opinion.
• No issue with switching to decorators on parameters
• We should support a multi-parameter and multi-export syntax (similar to support a multi-* declaration (should support params, outputs at least, but likely more) #23). Suggested syntax is something like this:

parameters (
  foo string
  bar int
)

exports (
  someOutput bool
  otherOutput string
)

Brackets on resource loops

• We're ok using the resource[] syntax. An alternative suggestion would be to make resource more a type than a keyword. For example:

// single resource
resource<Microsoft.Storage/storageAccounts@2019-07-01> myStorage = {
  name: '...'
}

// resource loop
resource<Microsoft.Storage/storageAccounts@2019-07-01>[] myStorage = [
  for foo in foos: {
  name: '...'
}]

Filters

We're fine to defer the filter implementation. Can potentially investigate whether resource loops and conditions can be combined to achieve resource filtering, but it won't work for value filtering.

String literals

• No issue with defaulting to interpolated strings
• Suggested adding string syntax without interpolation enabled (similar to verbatim @ strings in C#). It would make typing certain symbols like $ without requiring escapes.
• Suggested implementing a multi-line/block strings. No preference on syntax. Suggested yaml block strings, but they do appear to have limitations around white-space sensitivity.
• Discussed removing quotes from string literals to make it more like YAML, but cannot do that due to expressions.

Automatic Semicolon Insertion/whitespace sensitivity

• We need to ensure that that there are no ambiguities due to ASI like in JS.

Decompiler/Round-tripping

• Decompiler should be a separate tool from core bicep intended for migration only. Doesn't need to be perfect.

Resource declarations

• Dependencies could be a decorator instead of a property in the resource body to separate metadata from resource body.

Modules

• Module reference syntax looks good.
• We should consider supporting "native modules" (referencing a JSON template as if it were a bicep module). This will simplify transition without forcing people to rewrite all their stuff.
• Supportive of multi-file modules with single-file option.
• We have a potential issue with current module design where the user could accidentally include a file in a module simply by dropping it in a folder. This could result in unnecessary resources being added in the module or simply squiggles in VS code due to symbolic name clashes. Suggestion is to have an optional module name declaration at the top of the file to make opt-in intentional. (Files in the same module would have to specify the same module name matching the directory name.)

[lwang2016]

Does export mean output here? Does it mean a module's contract might not be strongly typed?

[majastrz]

Yeah export means output in our current syntax. (Option 3 from #81) I think Brendan was fine if we make type required on exports.

[lwang2016]

Yeah export means output in our current syntax. (Option 3 from #81) I think Brendan was fine if we make type required on exports.

I would strongly prefer making type required. :)

[majastrz]

Discussed the feedback in team meeting on 7/28. Here are the takeaways:

• Allow existing syntax for outputs as well as the split syntax that Brendan suggested.
• Types will be required on outputs as they are contracts.
• Multi-parameter and multi-output syntax makes sense. Will add it to the list.
• Will put brackets on resource for resource loops.
• Will use @ for verbatim strings (a string interpolation "disabler")
• On module declarations, the team pushed back on needing top level declaration for module name. The thinking is that terraform doesn't have it and it's not a problem. Can potentially consider having project files to control what is included in a module.

@marcre, @lwang2016, @snarkywolverine, @jorgecotillo and others please let me know if I missed anything here.

[alex-frankel]

• is @ being overloaded if we use it as an annotation syntax? It seems cleaner to use an alternate quote type (most likely ...).
• will we still require brackets on the list comprehension ([for thing in things : {...}])
  • will we require [] on other list types (e.g. variable[] thing = [for thing in things : thing.name]
• I don't love the idea of planning on a project file as a solution to the module scoping problem. Can we potentially decide later to introduce a module name declaration if it becomes a problem?

[majastrz]

• is @ being overloaded if we use it as an annotation syntax? It seems cleaner to use an alternate quote type (most likely ...).

Good pt on overloading the @. Another type of quote makes sense to me.

• will we still require brackets on the list comprehension ([for thing in things : {...}])

We didn't discuss removing the list comprehension brackets at all.

• will we require [] on other list types (e.g. variable[] thing = [for thing in things : thing.name]
• I don't love the idea of planning on a project file as a solution to the module scoping problem. Can we potentially decide later to introduce a module name declaration if it becomes a problem?

That's what we said at the meeting. Let's see if it is a problem first and then add it later if it is.

[alex-frankel]

Just realized GH at my quote syntax :) meant to write `...`

What about brackets on non-resource arrays?

variable[] thing = [for thing in things : thing.name]

[majastrz]

Spent most of the team meeting today re-discussing the issues:

• placement of brackets on resource loops and will remain with the resource[] approach given that the underlying semantic is different.
• we will not add brackets to the other keywords
• we will keep the enclosing brackets around the list comprehension until we get feedback to remove them
• will add better array types (string[], for example) for parameters and outputs
• will discuss string interpolation syntax with Anders (@marcre suggested staying away from backticks or other quotes because they are hard to read and some tools (like Outlook) alter them when copy/pasting).
• team agrees that if we ever need a module name declaration, we prefer a top-level declaration in the file over a project file (i.e. project file is the last resort)

[majastrz]

The discussion regarding resource loop brackets placement also provoked a new direction for array parameters. Captured a proposal in #114.