Provisioning templates documentation


Today there’s a lack of knowledge among users and developers what each of the provisioning template does. Some templates have an erb comment, some not even that. We introduced a description attribute for template a while ago but we never filled that in for templates we ship by default.

I propose we start using it for this purpose. The description can be stored in a metadata section, therefore remain in the erb, however during import/seeding it gets parsed and stored in the description. That would result in ability to see it in the first tab in the edit form as well as in the editor.

I went through all the templates and provided the information I knew or found. With that I opened a draft PR. It would be great if you also share you knowledge in form of suggestions in the PR. Feel free to extend or add any missing information. I’ll ping few people that I think should have the knowledge in the PR.

Longer term, I’d like to reopen Fixes #23569 - store metadata separately from template by ares · Pull Request #5545 · theforeman/foreman · GitHub and parse out metadata on import, so user wouldn’t see it in the editor at all as it takes a lot of space.

When I was going through the templates I’ve seen a lot of outdated stuff. I made some notes what templates should be probably removed but that’s a separate RFC.