[package.proto] add canonical_base_url field.

recipe_engine/package.proto

 // Copyright 2016 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.
 
 // Recompile with libprotoc 2.5.0:
 // protoc -I recipe_engine recipe_engine/package.proto --python_out=recipe_engine
 
 syntax = "proto2";
 
 package recipe_engine;
 
 message DepSpec {
+  // Same meaning as Package.project_id, but the id for this dependency. This
+  // should always match the project_id of the repo that we're depending on.
   optional string project_id = 1;
+
+  // The url of where to fetch the package data. Must always be a git repo url.

[dnj, 2017/03/07 18:58:53]

Let's capitalize things like "URL" and "ID" :)

[iannucci, 2017/03/08 03:28:36]

Done.

   optional string url = 2;
+
+  // The ref to git-fetch when syncing this dependency.
   optional string branch = 3;
+
+  // The git commit ID that we depend on.

[martiniss, 2017/03/07 18:56:38]

commit ID? Is that the technical term? I would have said revision hash, but you
might know git better than me :)

[dnj, 2017/03/07 18:58:52]

Is the correct term a commit ID or a commit?

[iannucci, 2017/03/08 03:28:37]

both, I think. `object identity` is the sha1. 'commit' is fine though.

   optional string revision = 4;
 
-  // Treat a subtree of a repo as a whole repo unto itself.
+  // Treat a subtree of a repo as a whole repo unto itself. This must match
+  // the value of `recipes_path` in the target repo.
   optional string path_override = 5;
 
   enum RepoType {
     GIT = 0;
     GITILES = 1;
   }
+  // How this dependency should be fetched. GIT will do a full clone of the
+  // dependency, and GITILES will pull the data via the GITILES REST API.

[dnj, 2017/03/07 18:58:52]

Put these per-enum docs up by the enums themselves.

[iannucci, 2017/03/08 03:28:36]

Done.

+  //
+  // NOTE: this option may be removed in the future in preference for
+  // automatically picking the repo fetch method.
   optional RepoType repo_type = 6 [default = GIT];
 }
 
 message Package {
+  // The "API Version" of this proto. Should always equal 1, currently. This may

[dnj, 2017/03/07 18:58:52]

Document that this MUST always have a tag value of "1" even if it is changed
incompatibly.

[iannucci, 2017/03/08 03:28:36]

Done.

+  // change if a backwards-incompatible update must be done for the proto.
   optional int32 api_version = 1;  // Version 1
+
+  // The "id" of how this package is referred to within recipes. This becomes
+  // the prefix in DEPS when something depends on one of this package's modules
+  // (e.g.  DEPS=["recipe_engine/path"]).

[dnj, 2017/03/07 18:58:52]

Maybe mention naming constraints (e.g., no slashes, etc.)

[iannucci, 2017/03/08 03:28:36]

Done.

   optional string project_id = 2;
+
+  // The path (using POSIX-style slashes) to where the base of the recipes are

[dnj, 2017/03/07 18:58:52]

Just say "forward slashes".

[iannucci, 2017/03/08 03:28:36]

Done.

+  // found in the repo (i.e. where the "recipes" and/or "recipe_modules"
+  // directories live).
   optional string recipes_path = 3;
+
+  // Any package dependencies that this package has.
   repeated DepSpec deps = 4;
+
+  // The "source of truth" for this package's data, e.g.
+  //   "https://github.com/luci/recipes-py"
+  // This is used for documentation purposes, and does NOT need to match the
+  // `url` field in any other package's deps (in order to allow for mirroring).
+  //
+  // The documentation generator will infer paths to files that are relative to
+  // this URL, and knows about the following git host URL schemes:
+  //   * Github

[dnj, 2017/03/07 18:58:52]

nit: GitHub

[iannucci, 2017/03/08 03:28:36]

Done.

+  //   * Gitiles
+  optional string canonical_base_url = 5;
 }

[martiniss, 2017/03/07 18:56:38]

Shouldn't you update the recipes.cfg in here with this?

[iannucci, 2017/03/08 03:28:37]

Done.