over the time, Foreman gathered a lot of template parameters. I am starting an attempt to document them all and mark those which can be deprecated (e.g. same functionality under different names or template types - debian vs redhat).
I need your help! I can probably document all the bare-metal provisioning related, however we have many more, plugins and bunch of katello-related stuff. Please spend a minute and review this list and fill description for those you know what they do! Thank you.
I will be taking this list and turning it into a YAML so Foreman would actually check for description presence. Something like this (rough proposal):
# Documentation for template parameters. Rules when editing:
# * Prefer lower-case-dash-separated parameter names.
# * Keep description short and on point.
# * Try to keep the list sorted
description: 'Brief description. Can be multiple sentences but no newlines.'
context: 'Where it can be used (e.g. Kickstart, Remote execution).'
From here, this could be easily transformed into our documentation or even used within Foreman application to show on template edit page. Heck we could even do parameter competition in the edit component if we have spare cycles
Foreman is a beast, let’s help our users to find what they need.
This is a great activity, I’ll try contirbute to the documentation for sure.
I think it would be much better to actually seed all parameters with their default values. That way user can see the values in provisioning form and can overide easily for a given host (or on other levels we support). The seed file could still read it from the YAML, like we do with the templates. Parameters today don’t have a description, but that’s trivial to add.
Oh I understand now. So when you create new host, it would have 40 of parameters already prefilled with default values? This could easily be bad experience too tho.
That’s indeed an interesting idea. Is having all the parameters in seeds better place than a yaml? We would need to create documentation column as well.
On the other hand, we have similar thing with settings and after all those years, I think setting defaults and descriptions should rather have been defined outside of the DB (in a yaml perhaps). It requires seeding and keeping those up-to-date.
I agree. This will clutter the UI with a lot of parameters that are irrelevant in the majority of cases, as we are showing all of the global parameters (or any of the other parameters that match the host for that matter) on the host form. In most cases the templates have sort of a “default value” for what to do when the parameter isn’t defined, so users only need to set the parameter if they want to stray from that default.
However long-term it’s the best solution I think. Description really belong in here, not somewhere else. And if I want to implement descriptions, which is the main goal of this effort putting all the cleanup aside, it probably the best approach.
I’d add also new field named “group” where I’d group parameters together:
From here the UI team can pick up and deliver quite good experience.