Usability of 'samba-tool domain provision'

[Alexander Bokovoy]

On Wed, 04 May 2016, Rowland Penny wrote:
> On 04/05/16 14:44, Alexander Bokovoy wrote:
> > On Wed, 04 May 2016, Rowland Penny wrote:
> > > On 04/05/16 13:40, Alexander Bokovoy wrote:
> > > > On Wed, 04 May 2016, Rowland Penny wrote:
> > > > > On 04/05/16 12:16, Alexander Bokovoy wrote:
> > > > > > On Wed, 04 May 2016, Peter C. Kelly wrote:
> > > > > > > Andreas said:
> > > > > > > 
> > > > > > > > This documents issues I
> > > > > > > > found during provisioning. samba-tool is far away from being user friendly.
> > > > > > > > a) It isn't clear what domain is from 'samba-tool domain provison --help'
> > > > > > > I have raised bug 11894, and attached a patch which addresses this
> > > > > > > point as per Rowland's suggested wording.
> > > > > > > 
> > > > > > > > b) The --realm option is essential but at the end of the help ...
> > > > > > > The reason that the realm is way down the bottom is that it is under a
> > > > > > > heading "Samba Common Options", along with configFile debuglevel and
> > > > > > > option.
> > > > > > > 
> > > > > > > What is currently holding me up from developing the second trivial
> > > > > > > patch is a need for a bit more clarity on how this --help output
> > > > > > > should look.  It seems to me that if the --domain parameter is
> > > > > > > compulsory, then the heading text should say so,
> > > > > > > and that if a realm has to be specified (or read in from an existing
> > > > > > > conf file) then perhaps that should be mentioned in the introductory
> > > > > > > text as well.
> > > > > > It would, perhaps, be good to have it in both categories to avoid
> > > > > > changing common options' help.
> > > > > > 
> > > > > It doesn't need to be in both categories, if you do an interactive
> > > > > provision, there is this:
> > > > > 
> > > > >               realm = ask("Realm", default)
> > > > >               if realm in (None, ""):
> > > > >                   raise CommandError("No realm set!")
> > > > > 
> > > > > If you specify everything with the command, there is this:
> > > > > 
> > > > >               realm = sambaopts._lp.get('realm')
> > > > >               if realm is None:
> > > > >                   raise CommandError("No realm set!")
> > > > > 
> > > > > So, if you don't provide the 'realm', it refuses to continue and tells you
> > > > > why.
> > > > There is a difference between running the tool and reading the
> > > > documentation. ;) If we can improve expectations by pointing out that
> > > > realm and other options are really not options here but required
> > > > arguments, it would save some time to people who want to automate.
> > > > Manual page for samba-tool is very short on what could be expected from
> > > > the user in specific commands, unfortunately. The help output isn't
> > > > helping too.
> > > > 
> > > Well, if you run 'samba-tool domain provision --help', you get this at the
> > > top:
> > > 
> > > Usage: samba-tool domain provision [options]
> > > 
> > > Provision a domain.
> > > 
> > > 
> > > There then follows the list of options.
> > > 
> > > I am sure that 'Provision a domain' can be expanded on, starting with ', you
> > > must supply the realm name.'
> > > 
> > Yes, and even more, telling that at least realm, domain, and some other
> > options could be specified explicitly or will be asked for if they are
> > missing. Now, the issue I see is that current help makes no difference
> > between options which are required (i.e. they are not really options)
> > and therefore will be asked for if they were not specified and options
> > which tune default behavior but otherwise aren't necessary.
> > 
> > Right now there is no way to know about it other than running the tool
> > and learning the hard way by failing installation or making wrong
> > deployment. This is pretty bad user experience.
> > 
> 
> The problem is 'provision' works in two ways, 'interactive' and by giving
> all the answers to the command. This means you cannot make '--domain' a
> requirement without breaking 'interactive'. If we go down the line of making
> things compulsory, then we will probably have to remove the 'interactive'
> parts, do we want to do this ?
There is no problem at all. In fact, you are mixing different things.
I'm talking about the help message which needs to have better
explanation of what options are required and what options are to tune
the behavior. If you would do that, together with a statement that
missing values for 'required' options would be asked interactively, that
would be all that is needed.

I'm not asking in forcing 'required' options. I'm asking to make the
explanation of what is required and what is optional _discoverable_
without a need to always to run interactive version to discover the fact.



-- 
/ Alexander Bokovoy