Merge lp:~joetalbott/adt-cloud-worker/user_docs into lp:adt-cloud-worker

[Joe Talbott]

Add documentation for running tests locally like CI does.

Add documentation for running tests locally like CI does.

[Thomi Richards (thomir-deactivatedaccount)]

A few thoughts, which are only mild suggestions, feel free to ignore:

* I wonder if this is the best place for the docs?

* I suggest that the default documented command should be sans '-d' options, with a note that they can be added to increase the verbosity.

* The $PROXY env var isn't documented anywhere.

* What happens when we bump the timeout values we use in the service itself?

As an alternative approach, since the devs have the branch locally to be reading the docs, how about suggesting that they run something like:

python3 -c "import adt_cloud_worker; adt_cloud_worker.run_test(package='linux', result_dirt='/tmp/results'...)"

We can re-arrange the code to make that easier. Since one of the acceptance criteria is that the tests must be repeatable locally, this seems like it would be within the scope of the sprint, and would upgrade the 'connasence of value' too 'connasence of name' instead, which is an improvment.

Thoughts?

[Celso Providelo (cprov)]

Joe, few suggestions as inline comments, let me know what you think.

[Francis Ginther (fginther)]

I think the overall format for this good: make it obvious what the input is, then provide a nearly copy-n-paste example of how to run it.

This is kind of thing is tricky as we don't want to just document adt-run, there's already a man page for that (which we should point to along with a minimum required version). I really think it's best to expose the adt-run command directly as this should really drive people into using adt-run directly and make it clear that CI isn't doing anything special to make this work. So I think we should cover the uci-nova options, but leave anything adt-run specific to its man page.

[lp:~joetalbott/adt-cloud-worker/user_docs]

45. By Joe Talbott on 2015-04-30

Cleanup per review.

* Add prerequisites
* Clarify optional uci-nova arguments
* Simplify adt-run command example
* Explain caveats for special networking issues CI has to consider.

[Joe Talbott (joetalbott)]

I've pushed a new commit addressing most of the review comments. Please re-review and comment. Thanks.

[Celso Providelo (cprov)]

Joe,

Thanks for accepting my suggestions, there are still some adjustments pointed as inline comments, but since they are minor, I am pre-approving it.

review: Approve

[Francis Ginther (fginther)]

One correction in the comment I had passed along earlier. Otherwise this looks good. This just presents a single, most simple way to reproduce the test. I think we will soon get feedback on this and we'll have clear input on what needs to be tweaked from actual users.

Also approving pending the one change in the version.

review: Approve

[lp:~joetalbott/adt-cloud-worker/user_docs]

46. By Joe Talbott on 2015-04-30

Fix autopkgtest version and proxy example. Remove extraneous blank lines.

[Para Siva (psivaa)]

An inline comment, but +1

review: Approve

[lp:~joetalbott/adt-cloud-worker/user_docs]

47. By Joe Talbott on 2015-04-30

Indicate that only bootstack has been used for testing

[Joe Talbott (joetalbott)]

review: Approve

=== added file 'README-run-locally.rst'
--- README-run-locally.rst	1970-01-01 00:00:00 +0000
+++ README-run-locally.rst	2015-04-30 14:02:02 +0000
@@ -0,0 +1,65 @@
+How to run tests locally the same way they are run in CI.
+#########################################################
+
+Steps for running the dep8 tests for a  package the way they are run in CI.
+
+Prerequisites
+=============
+
+autopkgtest 3.11.2-0 or newer, available from ppa:canonical-ci-engineering/u-services
+
+Environment
+===========
+
+Set up the environment::
+
+    # Source your cloud credentials: This has only been tested on bootstack at the moment.
+    . ~/.novarc
+
+    # the package you want to test
+    export PACKAGE=some-package
+
+    # where results will be placed (the directory is created if it doesn't exist)
+    export RESULT_DIR=some-dir
+
+    # The IMAGE may change daily, be sure to check 'nova image-list'
+    export IMAGE=ubuntu-vivid-15.04-amd64-server-20150422-disk1.img
+
+    # (optional depending on your cloud)
+    # The neutron network uuid.
+    export NET_UUID=415a840-eb06-4e8a-906c-413c658f5bf6
+
+    # (optional)
+    # The archive mirror to use
+    export MIRROR=http://archive.ubuntu.com/
+
+    # (optional)
+    # The http proxy to use
+    export PROXY=http://127.0.0.1:3128/
+
+Running Tests
+=============
+
+Run the tests::
+
+    adt-run -d --apt-source $PACKAGE --output-dir $RESULT_DIR
+       --apt-pocket proposed --apt-upgrade \
+          --- ssh -s ./uci-nova -- --flavor m1.small --image $IMAGE
+
+
+The "-d"s may be omitted to reduce the verbosity of the output.
+
+If using a neutron network add to uci-nova arguments::
+
+    --net-id=$NET_UUID
+
+If a specific mirror is needed for the archive add this to uci-nova arguments::
+
+    --mirror=$MIRROR
+
+If an http proxy is needed add this to uci-nova arguments::
+
+    --proxy=$PROXY
+
+"--shell-fail" can be added to the adt-run arguments to push a shell on test failures.
+See adt-run(1) for the full list of adt-run arguments.