deploytool: Add README.md, migrate docs to it.

deploytool/api/deploy/config.proto

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 syntax = "proto3";
 
 package deploy;
 
 import "github.com/luci/luci-go/deploytool/api/deploy/checkout.proto";
 
 /**
- * The deployment configuration is a set of parameters composed from local and
- * source configuration files. Each configuration file is read as a text
- * protobuf in two stages:
+ * Layout defines the root directory of a deployment configuration.
  *
- * Local Stage
- * ============
- * First, the source and project layout configurations are loaded. These detail
- * the projects that are to be deployed and the source definitions for those
- * projects.
- *
- * Local configurations are located in subdirectories relative to a root
- * "layout.cfg" file:
- *
- * /layout.cfg
- * /sources/
- *   <source-group-name>/     (Defines a source group).
- *     <source-name>.cfg      (Defines a source within the source group).
- *
- * /applications/
- *   <application-name>.cfg   (Defines a application).
- *
- * /deployments/
- *   <deployment-name>.cfg    (Defines a deployment).
- *
- * Each "source" defines host repositories to check out with that source's name.
- * Sources can be pulled from a variety of places, and will be checked out into
- * uniquely-named staging directories.
- *
- * Each "application" defines a set of source-relative components that the
- * application is composed of. The components' definitions are located in the
- * deployment configuration area within their source.
- *
- * A "deployment" binds an "application" to a set of "sources" and
- * deployment-specific parameters (e.g., cloud project). A deployment's
- * configuration is composed of its application's components loaded from their
- * sources. Deployment operations are executed against deployments.
- *
- * Source Stage
- * ============
- * Each source referenced by the named application(s) will be checked out in a
- * staging area. Configurations referenced by the applications will then be
- * loaded from those sources to complete the deployment configuration.
+ * Each layout field has a default value, so an empty layout protobuf file is
+ * a valid layout. Each field may be overridden to suit your repository's
+ * structure, if needed.
  */
 message Layout {
   /**
    * If specified, the relative path to the sources configuration directory. If
    * empty, this will default to "sources".
    */
   string sources_path = 1;
 
   /**
    * If specified, the relative path to the applications configuration
@@ skipping 16 matching lines @@
 /**
  * Source represents a single source configuration file.
  *
  * It contains definitions for the set of source repositories that make up this
  * Source.
  *
  * Each source is defined within a source group directory, and is named
  * "<source-name>.cfg". The source can be referenced internally by its full
  * source path, "<source-group-name>/<source-name>".
  *
- * If the source root contains a ".luci-deploytool.cfg" file, it will be read
+ * If the source root contains a "luci-deploy.cfg" file, it will be read
  * and interepreted as a "SourceLayout" message.
  */
 message Source {
   /** GitRepo is a named Git repository. */
   message GitRepo {
     /**
      * URL is the base URL of the repository.
      *
      * If this is a "file://" URL, the local file path will be used as the
      * repository source.
@@ skipping 16 matching lines @@
    * Go Paths to add to this repository.
    *
    * This will be prepended to the GOPATH that the repository exports during its
    * configuration/initialization.
    */
   repeated GoPath go_path = 10;
 
   /**
    * If true, this repository is allowed to run scripts:
    * - At source initialization time, the initialization scripts defined in
-   *   ".luci-deploytool.cfg" will be executed.
+   *   "/luci-deploy.cfg" will be executed.
    * - At build time, build scripts associated with a Component will
    *   be executed. Note that if the a Component declares a build script and `run_scripts` is not true,
    *   the build will fail.
    *
    * It is important that this repository is trusted if this is set to true,
    * since this script will be run on the deployment system under the
    * deployment user account.
    */
   bool run_scripts = 11;
   /** If true, mark this as a tained source. */
@@ skipping 116 matching lines @@
   CloudProject cloud_project = 3;
 
   /**
    * Map of key/value parameters for this Deployment.
    *
    * These will be automatically substituted where parameter substitution is
    * allowed.
    */
   map<string, string> parameter = 4;
 }