Authoring tools: templates & template packages validation
- Dominant language
- No language data
- Stars
- 1.7k
- Forks
- 399
- Avg merge
- 3d 5h
- Merged PRs (30d)
- 39
Description
As a template author, I want a way to validate the templates, so that I can validate template before the publish.
**Audience**: template authors
## Background
The template configuration requires manual editing in of JSON configuration which is source of authoring mistakes.
The configuration involves a lot of conditions, which are not validated in any way until the template is being generated.
When grouping the templates the configuration is manually, and requires careful combination of the fields across multiple JSON files. The grouping errors are shown only when the template is being run (not when the package containing it is installed)
## Planned validation checks:
(note: though some of the issues are closed, their comments contain suggested validation check)
- Blacklist top level commands from allowed template names/shortnames
- Flag optional parameters without default value
- Flag parameters that are prefixes of others (this can create ambiguous situations when parsing expressions via tries)
- All forms applied to source name provide different results (warning, see https://github.com/dotnet/templating/issues/1920)
- All forms applied to symbol provide different results
- https://github.com/dotnet/templating/issues/3828
- https://github.com/dotnet/templating/issues/4268
- https://github.com/dotnet/templating/issues/5561 (nth)
- https://github.com/dotnet/templating/issues/3254
- https://github.com/dotnet/templating/issues/3127
- https://github.com/dotnet/templating/issues/5198
- https://github.com/dotnet/templating/issues/5671 - the template doesn't define `name` parameter/symbol
- https://github.com/dotnet/templating/issues/4650
## Justification
- decrease the number of issues when authoring 1st party templates and detecting them post PR/even releasing them
- improve easiness of authoring and quality of 3rd party templates; detect potential issues prior to testing
- improve UX for final users by not allowing to install invalid templates / warning about possible issues
## Technical details
We plan to expose 2 ways:
- via MSBuild tasks, see: https://github.com/dotnet/templating/issues/3828
- via authoring tools CLI
Both MSBuild task and CLI tool already exist.
As part of this task, the validation in template engine and `dotnet new` should be improved as well.
- when reading the template, the generator should ensure it has a minimum required set of information in order to proceed. The JSON parsing errors and basic errors and warnings should be exposed.
- when installing the template, the conflicts should be detected
- the host should be able to inject the checks for `host.json` file.
- the way to present the errors should be potentially implemented in host itself
Feedback from @sayedihashimi
- Templates shouldn’t have to be installed in order to be validated
- More specifically be able to pass in a folder path or a path to .nupkg file
- The tool should accept multiple values for folder path/path to .nupkg
- For authors that have developed several templates this would be helpful
- After running the tool it should return a non-zero exit code if the validation is not successful
- This will enable users to script the validate step, and be able to fail the CI build if so
- Error and warning messages should follow the MSBuild error/warning format so that errors/warnings should be auto-detected if a user executes the tool via an MSBuild file.
- The MSBuild team may know of any formal docs.
- [MSBuild book](https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Famzn.to%2F3mMBLUY&data=04%7C01%7Cvshubina%40microsoft.com%7Ccda6a1eb1a0d4738abbe08d87f750ca7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637399488001326850%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=PDWlvfCi4ORE%2B%2Bv8E5ifmJQHPn2TZawmbEHPwmmgpYU%3D&reserved=0)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.