#49793 Update format of the "dscreate example" output and rewrite the parameter descriptions
Closed: wontfix 3 years ago Opened 3 years ago by mmuehlfeldrh.

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.


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:

example_documentation.png

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

3 years ago

Metadata Update from @mreynolds:
- Issue assigned to mreynolds
- Issue close_status updated to: fixed
- Issue status updated to: Closed (was: Open)

3 years ago

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]

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.

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.

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.

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.

Thank you for understanding. We apologize for all inconvenience.

Metadata Update from @spichugi:
- Issue close_status updated to: wontfix (was: fixed)

2 years ago

Login to comment on this ticket.

Metadata