OLD | NEW |
---|---|
1 // Copyright 2016 The LUCI Authors. All rights reserved. | 1 // Copyright 2016 The LUCI Authors. All rights reserved. |
2 // Use of this source code is governed under the Apache License, Version 2.0 | 2 // Use of this source code is governed under the Apache License, Version 2.0 |
3 // that can be found in the LICENSE file. | 3 // that can be found in the LICENSE file. |
4 | 4 |
5 // Recompile with libprotoc 2.5.0: | 5 // Recompile with libprotoc 2.5.0: |
6 // protoc -I recipe_engine recipe_engine/package.proto --python_out=recipe_engin e | 6 // protoc -I recipe_engine recipe_engine/package.proto --python_out=recipe_engin e |
7 | 7 |
8 syntax = "proto2"; | 8 syntax = "proto2"; |
9 | 9 |
10 package recipe_engine; | 10 package recipe_engine; |
11 | 11 |
12 message DepSpec { | 12 message DepSpec { |
13 // Same meaning as Package.project_id, but the id for this dependency. This | |
14 // should always match the project_id of the repo that we're depending on. | |
13 optional string project_id = 1; | 15 optional string project_id = 1; |
16 | |
17 // 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.
| |
14 optional string url = 2; | 18 optional string url = 2; |
19 | |
20 // The ref to git-fetch when syncing this dependency. | |
15 optional string branch = 3; | 21 optional string branch = 3; |
22 | |
23 // The git commit ID that we depend on. | |
martiniss
2017/03/07 18:56:38
commit ID? Is that the technical term? I would hav
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. 'com
| |
16 optional string revision = 4; | 24 optional string revision = 4; |
17 | 25 |
18 // Treat a subtree of a repo as a whole repo unto itself. | 26 // Treat a subtree of a repo as a whole repo unto itself. This must match |
27 // the value of `recipes_path` in the target repo. | |
19 optional string path_override = 5; | 28 optional string path_override = 5; |
20 | 29 |
21 enum RepoType { | 30 enum RepoType { |
22 GIT = 0; | 31 GIT = 0; |
23 GITILES = 1; | 32 GITILES = 1; |
24 } | 33 } |
34 // How this dependency should be fetched. GIT will do a full clone of the | |
35 // 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.
| |
36 // | |
37 // NOTE: this option may be removed in the future in preference for | |
38 // automatically picking the repo fetch method. | |
25 optional RepoType repo_type = 6 [default = GIT]; | 39 optional RepoType repo_type = 6 [default = GIT]; |
26 } | 40 } |
27 | 41 |
28 message Package { | 42 message Package { |
43 // 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
iannucci
2017/03/08 03:28:36
Done.
| |
44 // change if a backwards-incompatible update must be done for the proto. | |
29 optional int32 api_version = 1; // Version 1 | 45 optional int32 api_version = 1; // Version 1 |
46 | |
47 // The "id" of how this package is referred to within recipes. This becomes | |
48 // the prefix in DEPS when something depends on one of this package's modules | |
49 // (e.g. DEPS=["recipe_engine/path"]). | |
dnj
2017/03/07 18:58:52
Maybe mention naming constraints (e.g., no slashes
iannucci
2017/03/08 03:28:36
Done.
| |
30 optional string project_id = 2; | 50 optional string project_id = 2; |
51 | |
52 // 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.
| |
53 // found in the repo (i.e. where the "recipes" and/or "recipe_modules" | |
54 // directories live). | |
31 optional string recipes_path = 3; | 55 optional string recipes_path = 3; |
56 | |
57 // Any package dependencies that this package has. | |
32 repeated DepSpec deps = 4; | 58 repeated DepSpec deps = 4; |
59 | |
60 // The "source of truth" for this package's data, e.g. | |
61 // "https://github.com/luci/recipes-py" | |
62 // This is used for documentation purposes, and does NOT need to match the | |
63 // `url` field in any other package's deps (in order to allow for mirroring). | |
64 // | |
65 // The documentation generator will infer paths to files that are relative to | |
66 // this URL, and knows about the following git host URL schemes: | |
67 // * Github | |
dnj
2017/03/07 18:58:52
nit: GitHub
iannucci
2017/03/08 03:28:36
Done.
| |
68 // * Gitiles | |
69 optional string canonical_base_url = 5; | |
33 } | 70 } |
martiniss
2017/03/07 18:56:38
Shouldn't you update the recipes.cfg in here with
iannucci
2017/03/08 03:28:37
Done.
| |
OLD | NEW |