1) Reformat the "dscreate example" comments/documentation. A better format is:
parameter_name (type) [REQUIRED|optional] Description: ... Default value: ... With this format, it's more obvious if a parameter is required. Currently, parameters which are not commented out in the exampe are requied - which is difficult to identify. This also reduces the amount of documentation work in the RHDS guides. We can just say that the admin needs only set the [REQUIRED]-flagged parameters for a minimal INF file and everything else is optional.
2) The descriptons of the parameters should be more descriptive. It makes more sense to have the more detailed descriptions in the product/upstream and to refer to them.
<img alt="0001-Updated-descriptions-in-dscreate-example-INF-file.patch" src="/389-ds-base/issue/raw/files/dd64070a444666198181a9cbbfeee0bd903363b520c0743daa2c6e90285e56b7-0001-Updated-descriptions-in-dscreate-example-INF-file.patch" />
The patch simplifies the documentation a lot. See the following screenshot, how easy it would be to document the installation procedure if we have all parameters documented in the product itself:
<img alt="example_documentation.png" src="/389-ds-base/issue/raw/files/ae4b1f87646cfaf0e5bafdc2bb2533341e01528307e3e2a02292b85f5601a703-example_documentation.png" />
Looks good to me
Metadata Update from @mreynolds: - Custom field component adjusted to None - Custom field origin adjusted to None - Custom field reviewstatus adjusted to ack - Custom field type adjusted to None - Custom field version adjusted to None - Issue set to the milestone: 1.4.0 - Issue tagged with: lib389
749b9f3..fa41aee master -> master
Metadata Update from @mreynolds: - Issue assigned to mreynolds - Issue close_status updated to: fixed - Issue status updated to: Closed (was: Open)
I have the following error:
# dscreate create-template > test # dscreate install test Error: Missing configuration config_version in section [general]
In the generated template I see:
[general] # config_version (int) [REQUIRED] # Description: Sets the format version of this INF file. To use the INF file with dscreate, you must set this parameter to "2". # Default value: 2 ;config_version = 2
This is a a required option and it is commented out. Looking at the template, it seems that all options are commented out, even the required ones.
I guess this is just a copy paste error: https://pagure.io/389-ds-base/blob/fa41aee93/f/src/lib389/lib389/instance/options.py#_104
I have the following error: dscreate create-template > test dscreate install test Error: Missing configuration config_version in section [general]
Error: Missing configuration config_version in section [general]
It's expected that all parameters are commented out and that instance creating fails if you don't comment them in.
This forces the users to explicitly set all [REQUIRED]-flagged parameters. Otherwise users might ignore/overlooks them and an instance will be configured with default settings, such as the Directory Manager password set to "directory manager password" or an instance named "localhost".
This also makes the documentation much simpler, because we can tell the user to, at minimum, uncomment and set all [REQUIRED]-flagged parameters to get a working instance. See the attached screenshot of my documentation above.
I uncommented only config_version and instance was created anyway, with default parameters.
config_version
Another thing is that config_version is an internal variable that points out that this config is not the same as .inf files for the previous releases. If it's autogenerated by dscreate, we know for sure that it's 2, not 1. Making user to uncomment it is not user-friendly, when we can do it automatically. As for the fqdn, DM's password and suffix - we don't fail if they are unset, which is also not user-friendly.
.inf
dscreate
I agree that config_version should not be required. The fqdn defaults to the local system name (socket.gethostname()). The DM password does get auto-created, but this really should be required, and the suffix is optional by design.
So IMO we should make config_version optional, and require rootdn password. FQDN and suffix are okay the way they are.
I'll open a new PR to address this...
I think it makes no sense that the four [REQUIRED] parameters have defaults. That is contradictory. If they have defaults, the user is not required to set them.
I propose the following: - Remove default value from instance_name (I guess nobody really wants an instance named "localhost") - Remove the default value from root_password - Change full_machine_name to [optional]. Here the default makes sense. - config_version: Whatever you prefer here :-)
@mmuehlfeldrh This is going to be changed. There are no longer going to be required parameters. Every option will have a default. So you can create a template and install it without any edits needed. We need it to work this way for containers. I'm handling that change in
https://pagure.io/389-ds-base/issue/49808
https://pagure.io/389-ds-base/pull-request/49809
FYI, Mark
389-ds-base is moving from Pagure to Github. This means that new issues and pull requests will be accepted only in 389-ds-base's github repository.
This issue has been cloned to Github and is available here: - https://github.com/389ds/389-ds-base/issues/2852
If you want to receive further updates on the issue, please navigate to the github issue and click on subscribe button.
subscribe
Thank you for understanding. We apologize for all inconvenience.
Metadata Update from @spichugi: - Issue close_status updated to: wontfix (was: fixed)
Login to comment on this ticket.