Merge lp:~rodsmith/checkbox/intro-docs into lp:checkbox

[Rod Smith]

Adds the notes from the training session with the server certification team as a part of the official Checkbox/PlainBox documentation. Note that I left the screen shots as such because this preserves reverse video formatting, which would be lost in a text-only conversion; however, I did crop the first two screen shots to reduce the amount of empty space.

Second submission addresses Daniel's comments.

Third submission addresses most of Zygmunt's comments; however:

- A few long lines exist because they involve extra-long URLs or code lines.
- It wasn't clear to me what Zygmunt wanted in his last two comments.
  I think it's best that he make his suggested edits himself to avoid the
  likelihood that I'd mangle his intended changes.

[Daniel Manrique (roadmr)]

Fantastic, thanks!

Some suggestions.

This document was meant to be stand-alone, so it includes a mini-glossary, but the plainbox documentation already has one here:

http://plainbox.readthedocs.org/en/latest/glossary.html

I'd suggest linking to that instead, you should be able to use :ref:`glossary` for that. Also, if my glossary has something different or missing in the global one, perhaps adding that to the global glossary to enrich it would be a good idea.

Next, see this section:

One way to deliver tests via PlainBox is to start your own provider. We have a very good document for Tutorial that:

http://plainbox.readthedocs.org/en/latest/author/tutorial.html

Since this lives in the same sphinx tree as the tutorial, you can use an internal reference to make this tidier. I'd change the above to:

One way to deliver tests via PlainBox is to start your own provider. To learn how to do that, see the :ref:`tutorial`.

Finally, maybe some gardening of the links at the end (so the ones referring to plainbox docs are turned into internal :ref: or :doc: links) would tidy things up a bit.

Still, this is good (thanks for cropping the screenshots, it's exactly what I was thinking about), so if you want to merge it as-is and iterate to improve it, I'd be fine with that.

[Zygmunt Krynicki (zyga)]

General request: I'd like to ensure that we keep the <80 (typically 76-79) columns in all text files. I can correct this after it lands if you prefer. If you are using vim all you need to do is to select each paragraph with V and use 'gq' to reflow the text. Usually the outcome is much easier to read.

[Zygmunt Krynicki (zyga)]

I'll give this a honest read over weekend. For now just one small inline comment down below

[Zygmunt Krynicki (zyga)]

Some more random notes inline.

[Rod Smith (rodsmith)]

Added comments on two of Zygmunt's suggested changes.

[Daniel Manrique (roadmr)]

Two replies to the comments (which may be outdated):

The syntax to run a plainbox job with -i involves giving the job name but it has to be fully namespaced. Example:

plainbox run -i 2013.com.canonical.certification::cpu/info

The prefix is normally 2013.com.canonical.certification unless you're using a custom namespace.

As for the sentence "I want to write a test to ensure that the ubuntu user exists", I'll play the non-native speaker card here. There should be no ambiguity since it uses "that" in a conjunction sense, rather than as a pronoun (http://www.merriam-webster.com/dictionary/that, I had to look that up). If I wrote this, it's probably an artifact of spanish where you always have to put the conjunction ('que' is used in that case). If you think it makes more sense to remove "that" (to ensure the ubuntu user exists) it can be done easily.

[Zygmunt Krynicki (zyga)]

On Monday, September 15, 2014, Roderick Smith <email address hidden>
wrote:

> Added comments on two of Zygmunt's suggested changes.
>

Thanks for getting back to that merge request Rod. I'm sorry for neglecting
it myself. We were talking with Daniel about merging it and doing some
post-merge editing but we got lost in our daily tasks.

I'll read the updated diff and reply again.

Thanks
ZK

[Brendan Donegan (brendan-donegan)]

Sorry but the form 'CheckBox' still drives me nuts :) It's 'Checkbox' as
per the project page: https://launchpad.net/checkbox !

</ocd> :)

On Mon, Sep 15, 2014 at 8:06 PM, Zygmunt Krynicki <
<email address hidden>> wrote:

> On Monday, September 15, 2014, Roderick Smith <email address hidden>
> wrote:
>
> > Added comments on two of Zygmunt's suggested changes.
> >
>
>
> Thanks for getting back to that merge request Rod. I'm sorry for neglecting
> it myself. We were talking with Daniel about merging it and doing some
> post-merge editing but we got lost in our daily tasks.
>
> I'll read the updated diff and reply again.
>
> Thanks
> ZK
>
> --
> https://code.launchpad.net/~rodsmith/checkbox/intro-docs/+merge/232753
> Your team Checkbox Developers is requested to review the proposed merge of
> lp:~rodsmith/checkbox/intro-docs into lp:checkbox.
>

[Zygmunt Krynicki (zyga)]

Let's merge it. Thanks a lot Rod, this is a good chunk of much needed introduction!

review: Approve

[Rod Smith (rodsmith)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 09/16/2014 03:12 AM, Brendan Donegan wrote:
> Sorry but the form 'CheckBox' still drives me nuts :) It's
> 'Checkbox' as per the project page: https://launchpad.net/checkbox
> !

FWIW, I went with CheckBox because that's what's in the Glossary
(which I did not write) of the document I was editing:

http://plainbox.readthedocs.org/en/latest/glossary.html

> On Mon, Sep 15, 2014 at 8:06 PM, Zygmunt Krynicki <
> <email address hidden>> wrote:
>
>> On Monday, September 15, 2014, Roderick Smith
>> <email address hidden> wrote:
>>
>>> Added comments on two of Zygmunt's suggested changes.
>>>
>>
>>
>> Thanks for getting back to that merge request Rod. I'm sorry for
>> neglecting it myself. We were talking with Daniel about merging
>> it and doing some post-merge editing but we got lost in our daily
>> tasks.
>>
>> I'll read the updated diff and reply again.
>>
>> Thanks ZK
>>
>> --
>> https://code.launchpad.net/~rodsmith/checkbox/intro-docs/+merge/232753
>>
>>
Your team Checkbox Developers is requested to review the proposed merge of
>> lp:~rodsmith/checkbox/intro-docs into lp:checkbox.
>>
>

- --
Rod Smith
Server and Cloud Certification Engineer
<email address hidden>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJUGC0OAAoJEFgyRI+V0FjmOrsH/jPkxk0Htt1Yr3Cer5vaf18l
WgXmGV6m+/Hp/IwvOsFJwHoJlZ7QTs6Ur/5kJWv9PtNIfvRRJ9AeOlL1cdgiYOeP
XJHKipvZ7AmNR9Mgb9/7x/n7Vmh/ZwBez10/v9b7GGgfwzseId0Ybd0CzXvL4lrJ
j2e5Qos9diTfrPgJgOQ958HAomkxpVVBukIFcERDlqH42H+3SsnZEdwMTKetUNAn
D6PyHsl1xZTllABkYS27/axr+jumeYopo0/Xkl3FSjTMVzhsDfvSuaLrfE5AinsQ
0oNpHxzJlLyNxCNtAGSkXyGQMF6QAvPhkqAa0k7smMBgWdzSZ7qIHjI4AQGbxRc=
=FW9X
-----END PGP SIGNATURE-----

[Brendan Donegan (brendan-donegan)]

On Tue, Sep 16, 2014 at 1:30 PM, Roderick Smith <email address hidden>
wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 09/16/2014 03:12 AM, Brendan Donegan wrote:
> > Sorry but the form 'CheckBox' still drives me nuts :) It's
> > 'Checkbox' as per the project page: https://launchpad.net/checkbox
> > !
>
> FWIW, I went with CheckBox because that's what's in the Glossary
> (which I did not write) of the document I was editing:
>
> http://plainbox.readthedocs.org/en/latest/glossary.html

Yeah - *somebody* decided to adopt that form in all the documentation they
wrote (looks at Zygmunt :P). Camel-case is just really unnatural and I hate
reading it in natural language. Code is fine because well we need to put up
with all sorts of unnatural structures in code, but camel-case should not
be permeating everywhere.

>
>
> > On Mon, Sep 15, 2014 at 8:06 PM, Zygmunt Krynicki <
> > <email address hidden>> wrote:
> >
> >> On Monday, September 15, 2014, Roderick Smith
> >> <email address hidden> wrote:
> >>
> >>> Added comments on two of Zygmunt's suggested changes.
> >>>
> >>
> >>
> >> Thanks for getting back to that merge request Rod. I'm sorry for
> >> neglecting it myself. We were talking with Daniel about merging
> >> it and doing some post-merge editing but we got lost in our daily
> >> tasks.
> >>
> >> I'll read the updated diff and reply again.
> >>
> >> Thanks ZK
> >>
> >> --
> >> https://code.launchpad.net/~rodsmith/checkbox/intro-docs/+merge/232753
> >>
> >>
> Your team Checkbox Developers is requested to review the proposed merge of
> >> lp:~rodsmith/checkbox/intro-docs into lp:checkbox.
> >>
> >
>
>
> - --
> Rod Smith
> Server and Cloud Certification Engineer
> <email address hidden>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1
>
> iQEcBAEBAgAGBQJUGC0OAAoJEFgyRI+V0FjmOrsH/jPkxk0Htt1Yr3Cer5vaf18l
> WgXmGV6m+/Hp/IwvOsFJwHoJlZ7QTs6Ur/5kJWv9PtNIfvRRJ9AeOlL1cdgiYOeP
> XJHKipvZ7AmNR9Mgb9/7x/n7Vmh/ZwBez10/v9b7GGgfwzseId0Ybd0CzXvL4lrJ
> j2e5Qos9diTfrPgJgOQ958HAomkxpVVBukIFcERDlqH42H+3SsnZEdwMTKetUNAn
> D6PyHsl1xZTllABkYS27/axr+jumeYopo0/Xkl3FSjTMVzhsDfvSuaLrfE5AinsQ
> 0oNpHxzJlLyNxCNtAGSkXyGQMF6QAvPhkqAa0k7smMBgWdzSZ7qIHjI4AQGbxRc=
> =FW9X
> -----END PGP SIGNATURE-----
>
> --
> https://code.launchpad.net/~rodsmith/checkbox/intro-docs/+merge/232753
> Your team Checkbox Developers is requested to review the proposed merge of
> lp:~rodsmith/checkbox/intro-docs into lp:checkbox.
>

=== added file 'plainbox/docs/author/cc1.png'
Binary files plainbox/docs/author/cc1.png	1970-01-01 00:00:00 +0000 and plainbox/docs/author/cc1.png	2014-09-15 18:39:32 +0000 differ
=== added file 'plainbox/docs/author/cc2.png'
Binary files plainbox/docs/author/cc2.png	1970-01-01 00:00:00 +0000 and plainbox/docs/author/cc2.png	2014-09-15 18:39:32 +0000 differ
=== added file 'plainbox/docs/author/cc3.png'
Binary files plainbox/docs/author/cc3.png	1970-01-01 00:00:00 +0000 and plainbox/docs/author/cc3.png	2014-09-15 18:39:32 +0000 differ
=== modified file 'plainbox/docs/author/index.rst'
--- plainbox/docs/author/index.rst	2014-09-10 15:47:37 +0000
+++ plainbox/docs/author/index.rst	2014-09-15 18:39:32 +0000
@@ -7,6 +7,7 @@
 core.
 
 .. toctree::
+   intro.rst
    tutorial.rst
    providers.rst
    jobs.rst

=== added file 'plainbox/docs/author/intro.rst'
--- plainbox/docs/author/intro.rst	1970-01-01 00:00:00 +0000
+++ plainbox/docs/author/intro.rst	2014-09-15 18:39:32 +0000
@@ -0,0 +1,419 @@
+Introduction to PlainBox
+========================
+
+.. contents::
+
+What is PlainBox?
+-----------------
+
+Many years ago, a dark sorcerer known only as CR3 created a testing tool
+called ``hw-test`` with the vision of running tests against hardware to
+bless the hardware and deem it as Ubuntu Certified.  There was great
+rejoicing.  From the crowd that gathered around this tool came requests and
+requirements for new features, new tests and new methods of doing things. 
+Over the subsequent years, a tool called CheckBox was created. It was the
+product of the design by committee philosophy and soon grew ponderous and
+difficult to understand except by a few known only as "The Developers."
+CheckBox's goal was to function as a universal testing engine that could
+drive several types of testing: end-users running tests on their systems,
+certification testing with a larger set of tests, and even OEM-specific
+testing with custom tests.
+
+A couple of years ago CheckBox started showing its age. The architecture
+was difficult to understand and to extend and the core didn't really scale
+to some things we wanted to do; however, the test suite itself was still
+quite valuable.
+
+Thus PlainBox was created, as a "plain CheckBox" and again, there was much
+rejoicing. It was originally meant to be a simpler library for creating
+testing applications and as a requirement, it was designed to be compatible
+with the CheckBox test/job definition format.
+
+Since then, PlainBox has become a large set of libraries and tools, but the
+central aim is still to write testing applications. Note that the term
+*CheckBox* is still used to refer to the test suite generically; *PlainBox*
+is used to refer to the new tool set "under the hood."
+
+Goal
+----
+
+The goal of these tools is of course to run tests. They use a test
+description language that was inherited from CheckBox, so it has many
+interesting quirks. Since CheckBox itself is now deprecated, we have been
+adding new features and improving the test description language so this is
+in some flux.
+
+Terminology
+-----------
+
+In developing or using PlainBox, you'll run into several unfamiliar terms.
+Check the :doc:`../glossary` to learn what they mean. In fact, you should
+probably check it now. Pay particular attention to the terms *CheckBox*,
+*PlainBox*, *job*, *provier*, and *whitelist*.
+
+Getting Started
+---------------
+
+To get started, we'll install PlainBox and ``checkbox-ng`` along with some
+tests and look at how they are organized and packaged.
+
+The newest versions are in our PPAs. We'll use the development PPA at
+``ppa:checkbox-dev/ppa``. From there we'll install ``plainbox``,
+``checkbox-ng``, and ``plainbox-provider-checkbox``.
+
+As an end user this is all I need to run some tests. We can quickly run
+``checkbox-cli``, which will show a series of screens to facilitate running
+tests. First up is a welcome screen:
+
+.. image:: cc1.png
+ :height: 178
+ :width: 800
+ :scale: 100
+ :alt: checkbox-cli presents an introductory message before enabling you to
+       select tests.
+
+When you press the Enter key, ``checkbox-cli`` lets you select which
+whitelist to use:
+
+.. image:: cc2.png
+ :height: 343
+ :width: 300
+ :scale: 100
+ :alt: checkbox-cli enables you to select which test suite to run.
+ 
+With a whitelist selected, you can choose the individual tests to run:
+
+.. image:: cc3.png
+ :height: 600
+ :width: 800
+ :scale: 100
+ :alt: checkbox-cli enables you to select or de-select specific tests.
+
+When the tests are run, the results are saved to files and the program
+prompts to submit them to Launchpad.
+
+As mentioned, ``checkbox-cli`` is just a convenient front-end for some
+PlainBox features but it lets us see some aspects of PlainBox.
+
+Looking Deeper
+--------------
+
+Providers
+`````````
+
+First, we installed some "provider" packages. Providers were designed to
+encapsulate test descriptions and their related tools and data. Providers
+are shipped in Debian packages, which allows us to express dependencies to
+ensure required external packages are installed, and we can also separate
+those dependencies; for instance, the provider used for server testing
+doesn't actually contain the server-specific test definitions (we try to
+keep all the test definitions in the CheckBox provider), but it does depend
+on all the packages needed for server testing. Most users will want the
+resource and CheckBox providers which contain many premade tests, but this
+organization allows shipping the tiny core and a fully customized provider
+without extraneous dependencies.
+
+A provider is described in a configuration file (stored in
+``/usr/share/plainbox-providers-1``). This file describes where to find all
+the files from the provider. This file is usually managed automatically
+(more on this later). A provider can ship jobs, binaries, data and
+whitelists.
+
+A **job** or **test** is the smallest unit or description that PlainBox
+knows about. It describes a single test (historically they're called
+jobs). The simplest possible job is::
+
+ id: a-job 
+ plugin: manual 
+ description: Ensure your computer is turned on. Is the computer turned on?
+
+Jobs are shipped in a provider's jobs directory. This ultra-simple example
+has three fields: ``id``, ``plugin``, and ``description``. (A real job
+should include a ``_summary`` field, too.) The ``id`` identifies the job
+(of course) and the ``description`` provides a plain-text description of
+the job. In the case of this example, the description is shown to the user,
+who must respond because the ``plugin`` type is ``manual``. ``plugin``
+types include (but are not limited to):
+
+ * ``manual`` -- A test that requires the user to perform some action and
+   report the results.
+ * ``shell`` -- An automated test that requires no user interaction; the
+   test is passed or failed on the basis of the return value of the script
+   or command.
+ * ``local`` -- This type of job is similar to a ``shell`` test, but it
+   supports creating multiple tests from a single definition (say, to test
+   all the Ethernet ports on a computer). Jobs using the ``local`` plugin
+   are run when PlainBox is initialized.
+ * ``user-interact`` -- A test that asks the user to perform some action
+   *before* the test is performed. The test then passes or fails
+   automatically based on the output of the test. An example is
+   ``keys/media-control``, which runs a tool to detect keypresses, asks the
+   user to press volume keys, and then exits automatically once the last
+   key has been pressed or the user clicks the skip button in the tool.
+ * ``user-interact-verify`` -- This type of test is similar to the
+   ``user-interact`` test, except that the test's output is displayed for
+   the user, who must then decide whether it has passed or failed. An
+   example of this would be the ``usb/disk_detect`` test, which asks the
+   user to insert a USB key, click the ``test`` button, and then verify
+   manually that the USB key was detected correctly.
+ * ``user-verify`` -- A test that the user manually performs or runs
+   automatically and requires the user to verify the result as passed or
+   failed.  An example of this is the graphics maximum resolution test
+   which probes the system to determine the maximum supported resolution
+   and then asks the user to confirm that the resolution is correct.
+
+A fairly complex example definition is::
+
+ plugin: local
+ _summary: Automated test to walk multiple network cards and test each one in sequence.
+ id: ethernet/multi_nic
+ requires:
+  device.category == 'NETWORK'
+ _description: Automated test to walk multiple network cards and test each one in sequence.
+ command:
+  cat <<'EOF' | run_templates -s 'udev_resource | filter_templates -w "category=NETWORK" | awk "/path: / { print \$2 }" | xargs -n 1 sh -c "for i in \``ls /sys\$0/net 2>/dev/null\``; do echo \$0 \$i; done"'
+  plugin: shell
+  id: ethernet/multi_nic_$2
+  requires:
+   package.name == 'ethtool'
+   package.name == 'nmap'
+   device.path == "$1"
+  user: root
+  environ: TEST_TARGET_FTP TEST_TARGET_IPERF TEST_USER TEST_PASS
+  command: network test -i $2 -t iperf --fail-threshold 80
+  estimated_duration: 330.0
+  description:
+   Testing for NIC $2
+  EOF
+
+Key points to note include:
+
+ * If a field name begins with an underscore, its value can be localized.
+ * The values of fields can appear on the same line as their field names,
+   as in ``plugin: local``; or they can appear on a subsequent line, which
+   is indented, as in the preceding example's ``requires: device.category
+   == 'NETWORK'``.
+ * The ``requires`` field can be used to specify dependencies; if the
+   specified condition is not met, the test does not run.
+ * The ``command`` field specifies the command that's used to run the test.
+   This can be a standard Linux command (or even a set of commands) or a
+   CheckBox test script. In this example's ``local`` test definition, the
+   first ``command`` line generates a list of network devices that is fed
+   to an embedded test, which is defined beginning with the second
+   ``plugin`` line immediately following the first ``command`` line.
+ * In this example, the line that reads ``EOF`` ends the
+   ``ethernet/ethtool_multi_nic_$2`` test's command; it's matched to the
+   ``EOF`` that's part of ``cat << 'EOF'`` near the start of that command.
+
+Each provider has a ``bin`` directory and all binaries there are available
+in the path.
+
+Whitelists
+``````````
+
+In the job files we have a "universe" of known jobs. We don't normally want
+to run them all; rather we want to select a subset depending on what we're
+testing, and maybe give the user a way to fine-tune that selection. Also,
+we need a way to determine the order in which they will run, beyond what
+dependencies may provide. This is where the whitelist comes in; think of it
+as a mask or selection filter from the universe of jobs. Whitelists support
+regular expressions, and PlainBox will attempt to run tests in the order
+shown in the whitelist. Again, providers ship whitelists in a specific
+directory, and you can use ``plainbox`` to run a specific whitelist with
+the ``-w`` option.
+
+You can also use ``plainbox`` to run a test with the ``-i`` syntax. This is
+good for quickly running a job and ensuring it works well.
+
+Let's look at ``checkbox-cli`` for a moment. This is a "launcher"; it
+specifies a set of configuration options for a specific testing purpose.
+This enables us to create mini-clients for each testing purpose, without
+changing the core utility (``checkbox-launcher``). For instance, let's look
+at the launcher for ``canonical-certification-server``, which appears in
+``./providers/plainbox-provider-certification-server/launcher/canonical-certification-server``
+in the CheckBox source tree::
+
+ #!/usr/bin/env checkbox-launcher
+ [welcome]
+ text = Welcome to System Certification!
+     This application will gather information from your system. Then you will be
+     asked manual tests to confirm that the system is working properly. Finally,
+     you will be asked for the Secure ID of the computer to submit the
+     information to the certification.canonical.com database.
+     To learn how to create or locate the Secure ID, please see here:
+     https://certification.canonical.com/
+
+ [suite]
+ # Whitelist(s) displayed in the suite selection screen
+ whitelist_filter = ^((network|storage|usb|virtualization)-only)|(server-(full|functional)-14.04)$
+ # Whitelist(s) pre-selected in the suite selection screen, default whitelist(s)
+ whitelist_selection = ^server-full-14.04$
+
+ [transport]
+ submit_to = certification
+
+ [config]
+ config_filename = canonical-certification.conf
+
+A launcher such as this sets up an environment that includes introductory
+text to be shown to users, a filter to determine what whitelists to present
+as options, information on where to (optionally) submit results, and a
+configuration filename. This allows each provider to ship a launcher or
+binary with which to launch its relevant tests.
+
+Developing Tests
+````````````````
+
+One way to deliver tests via PlainBox is to start your own provider. To
+learn how to do that, see the :ref:`tutorial`.
+
+In other cases you want to add tests to the main CheckBox repository (which
+is also what we recommend to keep tests centralized, unless they're so
+purpose-specific that this makes no sense).
+
+This is a bit easier because the provider in question already exists. So
+let's get started by branching a copy of ``lp:checkbox``. In brief, you
+should change to your software development directory and type ``bzr branch
+lp:checkbox my-branch`` to create a copy of the ``checkbox`` Launchpad
+project in the ``my-branch`` subdirectory. You can then edit the files in
+that subdirectory, upload the results to your own Launchpad account, and
+request a merge.
+
+To begin, consider the files and subdirectories in the main CheckBox
+development directory (``my-branch`` if you used the preceding ``bzr``
+command without change):
+
+ * ``checkbox-gui`` -- CheckBox GUI components, used in desktop/laptop
+   testing
+ * ``checkbox-ng`` -- The PlainBox-based version of CheckBox
+ * ``checkbox-support`` -- Support code for many providers
+ * ``checkbox-touch`` -- A CheckBox frontend optimized for touch/tablet
+   devices
+ * ``mk-venv`` -- A symbolic link to a script used to set up an environment
+   for testing CheckBox
+ * ``plainbox`` -- A Python3 library and development tools at the heart of
+   PlainBox
+ * ``plainbox-client`` -- Unfinished Python3 interface for CheckBox
+ * ``providers`` -- Provider definitions, including test scripts
+ * ``README.md`` -- A file describing the contents of the subdirectory in
+   greater detail
+ * ``setup.py`` -- A setup script
+ * ``support`` -- Support code that's not released
+ * ``tarmac-verify`` -- A support script
+ * ``test-in-lxc.sh`` -- A support script for testing in an LXC
+ * ``test-in-vagrant.sh`` -- A support script for testing with Vagrant
+ * ``test-with-coverage`` -- A link to a support script for testing with
+   coverage
+ * ``Vagrantfile`` -- A Vagrant configuration file
+
+Let's say I want to write a test to ensure that the ubuntu user exists in
+``/etc/passwd``. You need to remove any existing CheckBox provider
+packages, lest they interfere with your new or modified tests. The
+``setup.py`` script will set up a PlainBox development environment for you.
+
+We can write a simple job here, then add a requirement, perhaps a
+dependency, then a script in the directory. Note that scripts can be
+anything that's executable, we usually prefer either shell or Python but
+anything goes.
+
+PlainBox will supply two environment variables, ``PLAINBOX_PROVIDER_DATA``
+and ``SHARE``, we usually try to use them in the job description only, not
+in the scripts, to keep the scripts PlainBox-agnostic if possible.
+
+Once the test is running correctly, we can create a whitelist with a few
+tests and name it.
+
+Once we get everything running correctly we can prepare and propose a merge
+request using ``bzr`` as usual.
+
+Other Questions
+---------------
+
+ **What Python modules are useful?**
+  I usually Google for the description of the problem I'm trying to solve,
+  and/or peruse the Python documentation in my spare time. I recommend the
+  *Dive Into Python* books if you have experience with another language, as
+  they are very focused on how to translate what you know into Python. This
+  applies also to Pythonisms like iterators, comprehensions, and
+  dictionaries which are quite versatile, and others. Again, the *Dive*
+  books will show you how these work.
+
+ **Are there other tools to use?**
+  ``flake8`` or ``pyflakes``, it's always a good idea to run this  if you
+  wrote a Python script, to ensure consistent syntax. ``manage.py
+  validate`` and ``plainbox dev analyze`` are also good tools to know
+  about.
+
+ **Is there a preferred editor for Python programming?**
+  I don't really know of a good editor/IDE that will provide a lot of help
+  when developing Python, as I usually prefer a minimalistic editor. I'm
+  partial to ``vim`` as it has syntax coloring, decent formatting
+  assistance, can interface with ``git`` and ``pyflakes`` and is just
+  really fast. We even have a plugin for PlainBox job files. Another good
+  option if you're not married to an editor is sublime text, Zygmunt has
+  been happy with it and it seems easy to extend, plus it's very
+  nice-looking. A recent survey identified Kate as a good alterntive. The
+  same survey identified ``gedit`` as *not* a good alternative so I'd avoid
+  that one. Finally if you're into cloud, ``cloud9.io`` may be an option
+  although we don't have a specific PlainBox development setup for it.
+
+References
+----------
+
+ :doc:`Reference on PlainBox test authoring <index>`
+
+ :doc:`jobs`
+
+ :doc:`PlainBox provider template <provider-template>`
+
+ :doc:`Provider and job writing tutorial <tutorial>`
+
+ :doc:`../dev/intro`
+
+ :doc:`What resources are and how they work <../dev/resources>`
+
+ :doc:`Man pages on special variables available to jobs <../manpages/PLAINBOX_SESSION_SHARE>`
+
+ :doc:`All the manpages <../manpages/index>`
+
+ `The CheckBox stack diagram`_
+
+.. _The CheckBox stack diagram:
+   http://checkbox.readthedocs.org/en/latest/stack.html
+
+ `Old CheckBox documentation for nostalgia`_
+
+.. _Old CheckBox documentation for nostalgia:
+   https://wiki.ubuntu.com/Testing/Automation/CheckBox
+
+ `Usual Python modules`_
+
+.. _Usual Python modules: https://docs.python.org/3.3/
+
+ `Document on upcoming template units feature`_
+
+.. _Document on upcoming template units feature:
+   http://bazaar.launchpad.net/~checkbox-dev/checkbox/trunk/view/head:/plainbox/docs/manpages/plainbox-template-units.rst
+
+ `A quick introduction to Bazaar and bzr`_
+
+.. _A quick introduction to Bazaar and bzr:
+   http://doc.bazaar.canonical.com/bzr.dev/en/mini-tutorial/
+
+ `A tool to use git locally but be able to pull/push from Launchpad`_
+
+.. _A tool to use git locally but be able to pull/push from Launchpad: http://zyga.github.io/git-lp/
+
+ `A video on using git with Launchpad`_
+
+.. _A video on using git with Launchpad:
+   https://plus.google.com/115602646184989903283/posts/RCepekrA5gu
+
+ `A video on how to set up Sublime Text for PlainBox development`_
+
+.. _A video on how to set up Sublime Text for PlainBox development:
+   https://www.youtube.com/watch?v=mrfyAgDg4ME&list=UURGrmUhQo5P9hTbVskIIjoQ
+
+ `CheckBox(ng) documentation home`_
+
+.. _CheckBox(ng) documentation home: http://checkbox.readthedocs.org

=== modified file 'plainbox/docs/glossary.rst'
--- plainbox/docs/glossary.rst	2014-03-12 20:05:37 +0000
+++ plainbox/docs/glossary.rst	2014-09-15 18:39:32 +0000
@@ -21,12 +21,30 @@
         available at http://launchpad.net/checkbox. The ``checkbox`` package is
         pre-installed on all Ubuntu systems
 
+    Checkbox-ng
+  
+	This is the actual direct replacement for CheckBox. It provides a
+	few binaries that can do end-user testing, and which leverage
+	PlainBox as a library to do the heavy lifting. This lives in the
+	``checkbox-ng`` package for the binaries, and
+	``python3-checkbox-ng`` for the core functionality.
+
     PlainBox
 
         PlainBox is a rewrite of CheckBox with the aim of improving internal
         architecture, testability, robustness, quality and speed. It is
         currently under active development. It is not pre-installed on Ubuntu.
-        It is developed inside CheckBox code repository.
+        It is developed inside the CheckBox code repository. In common
+	use, the term *PlainBox* can refer to either of two things:
+
+         * The core library (``python3-plainbox``). ``python3-plainbox`` is
+           usually installed implicitly, as most of our tools depend on it.
+
+         * The ``plainbox`` utility/binary, which is essentially a
+           command-line swiss-army frontend to all of the library's
+           functionality. It's useful for develoment and diagnostics but not
+           necessary for end-user work. ``plainbox`` is usually installed
+           explicitly if needed.
 
     whitelist