vpython: Add README and environment protobuf.

vpython/api/env/spec.proto

Index: vpython/api/env/spec.proto
diff --git a/vpython/api/env/spec.proto b/vpython/api/env/spec.proto
new file mode 100644
index 0000000000000000000000000000000000000000..ac4fa5a8e7dd91617a729a9545fdd6fb9e89bbd6
--- /dev/null
+++ b/vpython/api/env/spec.proto
@@ -0,0 +1,45 @@
+// Copyright 2017 The LUCI Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+syntax = "proto3";
+
+package env;
+
+
+message Spec {
+  // The Python version to use. This should be of the form:
+  // "Major[.Minor[.Patch]]"
+  //
+  // If specified,
+  // - The Major version will be enforced absolutely. Python 3 will not be
+  //   preferred over Python 2 because '3' is greater than '2'.
+  // - The remaining versions, if specified, will be regarded as *minimum*
+  //   versions. In other words, if "2.7.4" is specified and the system has
+  //   "2.7.12", that will suffice.

[iannucci, 2017/02/20 21:18:31]

And similarly '2.6' could get '2.7'?

This may lead to some issues though... e.g.
https://hg.python.org/cpython/raw-file/v2.7.9/Misc/NEWS which verifies https
certs by default. This could cause some code to go from working to !working
without any change to the dependencies, which is a bit meh :/

It's probably good to start this way though.

[dnj, 2017/02/22 06:39:11]

Done. Yeah, in all likelihood we can just say "2" unless otherwise needed.

+  //
+  // If empty, the default Python interpreter ("python") will be used.

[iannucci, 2017/02/20 21:18:31]

can we require that they specify at least a major version? If `python` ever
becomes `python -> python3`, we'd be in trouble.

[dnj, 2017/02/22 06:39:11]

Would we? Lots of packages are compatible with both.

I wouldn't mind actually not requiring this. It's trivial enough to specify, and
also trivial enough to go back and fix if a problem arises.

+  string python_version = 1;
+
+  // A definition for a remote package. The type of package depends on the
+  // configured package resolver.
+  message Package {
+    // The path of the package.
+    //
+    // - For CIPD, this is the package name.
+    string path = 1;
+
+    // The package version.
+    //
+    // - For CIPD, this will be a "version", which can include a "key:value"
+    //   ref/tag.

[iannucci, 2017/02/20 21:18:30]

"key:value" is a tag, "thing" is a ref

I would just say, "any recognized CIPD version (i.e. id, tag, or ref)".

[dnj, 2017/02/22 06:39:11]

Done.

+    string version = 2;
+  }
+  repeated Package wheel = 2;
+
+  // The VirtualEnv package.
+  //
+  // This should be left empty to use the `vpython` default package
+  // (recommended).
+  Package virtualenv = 3;
+}