Behaviour with a mix of New and Old options

In case the newly added options are used along with the ('soon to be'
deprecated) old options, the value from the new option is given precedence.

Added clarification in favour of this behaviour in the help string of
the old options - this is useful to know, while both the options co-exist!
Also added similar info in the docstring of the Python API.

Added tests to verify this behaviour - these tests need to be in force till
the Deprecation Notice holds!

stestr/tests/test_selection.py

@@ -204,8 +204,8 @@ def test_precedence_whitelist_vs_include_list(self):
         whitelist_file.close()
 
         result = selection.construct_list(test_lists,
-                                          include_list = 'include_file.txt',
-                                          whitelist_file = 'whitelist_file.txt')
+                                          include_list='include_file.txt',
+                                          whitelist_file='whitelist_file.txt')
         self.assertEqual({'fake_test1[tg]', 'fake_test2[tg]'}, set(result))
         # Cleanup
         os.remove('include_file.txt')