How should we organize content

[epage]

Inputs

• Allow evolution
• Don't break CIs
• Simple, naiive case should not lead user to unstable resources
  • If using branches for different versions, someone might naiively grab the URL for a master version of a script and we could end up breaking them
• Testability
• Azure Pipelines: each template repo has to be explicitly added in the resources
• Easy changelog management

[epage]

My primary concern atm is that our templates aren't versioned in any kind of way. This means we might break someone's CI if we need to make a breaking version.

The standard git model of creating a branch when we break won't work because people will be broken and then need to update to the branch.

Thoughts

• Have clients use a versioned branch only
• Have version be in the file or folder name.

[jonhoo]

Azure does let you use particular git refs for resources, so I think the trick here is going to be to keep one branch for every "breaking release" (basically just major semver version number). In the docs, we give examples with the ref always pointing to the latest such branch. We should (hopefully) break backwards compatibility very rarely with these, but it might happen. Then we'll just keep the latest one up-to-date with master until a breaking release must be made.

[jonhoo]

We now have a rough versioning scheme. Do we think that works sufficiently well to close this issue?