yellow team mailing list archive

[Francesco Banconi <francesco.banconi@xxxxxxxxxxxxx>]

lpsetup developer story
=======================

Terminology:

  - *host* is a machine that is the host for an LXC container.
  - *container* is an LXC container.
  - *target* is the environment created/changed by lpsetup, and can be
either a host or a container
  - *home* the user's home (usually bind mounted in the container)


1. Interactive execution
------------------------

We can subdivide modifications made by lpsetup into two types:

  - changes that are essential to achieve the goal of the lpsetup
command (e.g. init-host installs the Debian packages required to set up
a Launchpad env)
  - modifications the user can skip without affecting the program
execution (e.g. init-repo wants to set up bzr locations)

For essential changes:
We must give the user the chance to quit the process BEFORE any
modification is made to his system. A warning should inform the user
about what's going to happen, and the user must confirm to continue the
execution. If the user does not accept the conditions, the program exits.

For non-essential ones:
We could ask the user to accept to continue the execution DURING the
process. The user can opt out, that change is skipped, the program
continues normally.

We could implement a function like the following, (more or less stolen
from `fabric.contrib.console.confirm`)::

    def confirm(question, default=False):
        suffix = 'Y/n' if default else 'y/N'
        while True:
            response = raw_input('{0} [{1}] '.format(
                question, suffix)).lower()
            if not response:
                return default
            if response in ('y', 'yes'):
                return True
            if response in ('n', 'no'):
                return False
            print("I didn't understand you. Please specify '(y)es' or
'(n)o'.")

Note: I think the second interaction type (non-essential modifications)
could be just a nice to have, and we could release lpsetup with an "all
or nothing" interactive story.
Also note that the user can still skip steps using --skip-steps.

Actions:
- confirm function
- non-essential changes (decision needed)


2. Warnings
-----------

The user must be warned about modifications lpsetup wants to make to the
host and to the home.
The user can stop the execution if he is not in the mood (see above).

Commands:

  - init-host: warn about everything
  - init-lxc: warn about host changes and home changes, not container ones
  - init-repo: bzr locations file, I don't think we should warn about
the repository to be created... you are running init-repo, right?
  - update: no warnings, this command could be run daily, and an
interactive behavior would be annoying
  - install-lxc: warn about host changes and home changes, not container
ones
  - finish-inithost: warn about everything

How to display/collect warnings?
proposals::

  - output warnings inside each step, asking for confirmation
    - pros: easy, maybe simple (but I still haven't watched "Simple made
Easy" :-/)
    - cons: it's impossible to ask the user to accept everything at once
at the beginning of the process

  - override SubCommand.run() and warn the user there
    - pros: it's possible to quit the process immediately, we have a
single point describing everything done by that subcommand
    - cons: not DRY (steps used in several subcommands), it's difficult
to filter warnings if --steps or --skip-steps is provided

  - improve StepsBasedSubCommand to collect the warnings from steps
(e.g. parsing the docstring or from an attribute like step.description)
    - pros: it's possible to quit the process immediately, we can
display only warnings from steps that are actually run
    - cons: we extend the framework, we can lose flexibility (I don't
know why, that's just a feeling)

Ideas?

Actions:
- write descriptions/warnings
- collect and print them (decision needed)


3. Validation and error handling
--------------------------------

lpsetup currently has 3 validation layers::

  - arguments validation: this is already done by argparse
  - namespace validation (interaction between arguments): this is done
by handlers. They raise a ValidationError if something is wrong.
  - execution time validation: some arguments can be validated only
during steps execution (e.g. init-repo tries to create a repository in
the given directory). In these cases, the step must raise an ExecutionError.

Idea: ExecutionError also print the current step name?

Actions:
- for each sub command, implement, where not present, namespace and
execution time validation, in order to quit gracefully with an
informative error when arguments are invalid.


4. Debugging
------------

Actions:
- add a --debug or similar option that prints traceback and other useful
information (args, step name, etc.) when the program exits due to an
ExecutionError.


5. Logging
----------

In steps: print out what's going to happen?
Implement a proper logging (to screen and/or to file)?

Actions: decision needed.


6. File headers
---------------

Action: re-check headers are added to all created/modified configuration
files (in the host and in the home).


7. Testing story
----------------

Action1: Add a -y,--yes option to avoid interactions (and always answer
yes).

Action2: Add an option (defaulting to False) for each parallel testing
tweak: we already have flags for --stop-lxc, --install-subunit,
--use-http, --create-scripts. Add missing flags (e.g. haveged).

Action3: Add --testing option to install-lxc, as an alias for:
--stop-lxc --install-subunit --use-http --create-scripts --yes
--other-missing-flags. This can be done easily by fixing and
re-activating handle_testing().


8. Documentation
----------------

For users: the help command could be improved to include steps
description (see Warnings above).
For developers: document the "frameworky" bits of lpsetup?

-- 
Francesco Banconi