Clarified the development and tests md:

- Completed the "git clone" example.
- Added instructions to run "autogen.sh" before "make venv".
- Removed optional "git clean" command because it was found to be unnecessary.
  The Makefile gets regenerated anyway.
- Added "Testing"-section to doc/development.md because tests are optional for
  just building VDSM.
- Moved optional "configure" to Advanced-section because it's very rare that
  some parameters really need to be adjusted.
- Fixed broken "tox" example where the search path wasn'n specified resulting
  in too many tests being collected.
- Gave test examples for different modules because some need the explicit
  search path when passing arguments to pytest and some don't.
- Added --no-cov to examples for partial tests because the coverage warning
  is useless in those cases.
- Used multiple arguments in PYTEST_ADDOPTS to show how it's done.
- Simplified internal links to not be relative.
- Added warning about switching VDSM to maintenance mode before upgrading it.

Signed-off-by: Rob Linden [email protected]

doc/development.md

@@ -2,13 +2,6 @@
 
 ## Environment setup
 
-Fork the project on https://github.com/oVirt/vdsm.
-
-Clone your fork:
-
-    sudo dnf install -y git
-    [email protected]:{user}/vdsm.git
-
 Enable oVirt packages for Fedora:
 
     sudo dnf copr enable -y nsoffer/ioprocess-preview
@@ -24,36 +17,67 @@ Update the system after enabling all repositories:
 
     sudo dnf update -y
 
+Fork the project on https://github.com/oVirt/vdsm.
+
+Clone your fork:
+
+    sudo dnf install -y git
+    git clone [email protected]:{your_username}/vdsm.git
+
 Install additional packages for Fedora, CentOS, and RHEL:
 
     sudo dnf install -y `cat automation/check-patch.packages`
 
-Create virtual environment for vdsm:
+Generate the Makefile (and configure script):
+
+    ./autogen.sh --system --enable-timestamp
+
+Now you can create the virtual environment
+(https://docs.python.org/3/library/venv.html), which is necessary to run the
+tests later. This needs to be done only once:
 
     make venv
 
 
 ## Building Vdsm
 
-To configure sources (run `./configure --help` to see configuration options):
+Before building, it is recommended to recreate the Makefile because it
+contains version numbers, which might have changed by updating the local
+repository:
 
-    git clean -xfd
     ./autogen.sh --system --enable-timestamp
-    make
 
-To test Vdsm (refer to tests/README for further tests information):
+To build Vdsm:
 
-    make check
+    make
 
-To create an RPM:
+To create the RPMs:
 
     make rpm
 
-To upgrade your system with local build's RPM:
+To upgrade your system with local build's RPM (before you do this you should
+activate maintenance mode for Vdsm):
 
     make upgrade
 
 
+## Running the tests
+
+To run tests, first enter the virtual environment:
+
+    source ~/.venv/vdsm/bin/activate
+
+Then start some tests with tox, for example the networking tests:
+
+    tox -e network
+
+To exit the virtual environment afterwards:
+
+    deactivate
+
+For more information about testing see [/tests/README.md](/tests/README.md).
+
+
 ## Making new releases
 
 Release process of Vdsm version `VERSION` consists of the following
@@ -89,4 +113,10 @@ merged, we need to test them on all supported distributions and
 architectures.
 
 When you push patches to GitHub, CI will run its tests according to the
-configuration in the `.github/workflows/ci.yml` file.
+configuration in the `.github/workflows/ci.yml` file.
+
+
+## Advanced Configuration
+
+Before running `make` you could use `./configure` to set some (rarely used) options.
+To see the list of options: `./configure -h`.

tests/README.md

@@ -13,15 +13,26 @@ Note: Not all tests have been converted to tox and/or pytest yet.
 
 ## Running the tests
 
-Before running vdsm tests, activate the environment:
+Before running Vdsm tests, activate the virtual environment (which you need to
+create once, with `make venv`, as described in
+[/doc/development.md](/doc/development.md)):
 
     source ~/.venv/vdsm/bin/activate
 
-When done, you can deactivate the environment:
+When done with testing, you can deactivate the virtual environment:
 
     deactivate
 
-Before running storage tests, make sure you have setup the user storage
+To run tests from only one module, for example `lib`:
+
+    tox -e lib
+
+The test verbosity can be increased. Any arguments after `--` are passed
+through to pytest:
+
+    tox -e lib -- -vv
+
+Before running storage tests, make sure you have set up the user storage
 accordingly. To create storage you can do:
 
     make storage
@@ -32,20 +43,29 @@ for more information.
 
 Run storage tests:
 
-    tox -e storage
-
-Increasing test verbosity:
+    tox -e storage -- -vv --no-cov storage
 
-    tox -e storage -- -vv
+Note that for some test modules (like `storage` or `virt`), _if_ there
+are any extra pytest arguments (after the `--`) then the search path at
+the end needs to be specified explicitly, because the configuration in
+`tox.ini` doesn't take care of it in that case and unintended tests from
+other tox environments would be collected and run too.  
+Here we also disabled the coverage check, which is configured in
+`tox.ini`, because running subsets of the tests can't meet the desired
+coverage goal anyway and will just produce a useless warning. In this case
+some tests can only run as root. The same applies when we run the tests
+from just one file. But note that you also don't get any coverage reports
+in that case.
 
-You can also use environment variables:
+You can also use environment variables to pass options to pytest, then you
+don't have to worry about the search path:
 
-    export PYTEST_ADDOPTS=-vv
+    export PYTEST_ADDOPTS="--no-cov -vv"
     tox -e storage
 
-Running specific storage tests modules:
+To run the tests from just a single file:
 
-    tox -e storage -- storage/image_test.py
+    tox -e storage -- --no-cov storage/image_test.py
 
 Alternatively, all tests but storage tests can be run by doing: