Documentation: RobotLocomotion/drake@93e8964

Author: drake-jenkins-bot

buildcop.html

@@ -198,11 +198,14 @@ <h1 id="process">Process</h1>
 revert the commits and verify that the continuous builds triggered by that merge
 pass.</p>
 
-<p>In the case of failures in a <code class="language-plaintext highlighter-rouge">dev</code> directory, the build cop should disable the
-failing test instead of reverting the entire commit. To disable the test in
-certain configurations, add <code class="language-plaintext highlighter-rouge">opt_out_conditions = []</code> to its BUILD rule. If it
-fails in the default configuration or in too many configurations to list one by
-one, use <code class="language-plaintext highlighter-rouge">tags = ["manual"]</code> to universally disable the test.</p>
+<p>In the case of failures in an <code class="language-plaintext highlighter-rouge">experimental</code> or <code class="language-plaintext highlighter-rouge">dev</code> directory, the build
+cop should disable the failing test instead of reverting the entire commit. To
+disable the test in certain configurations, add <code class="language-plaintext highlighter-rouge">opt_out_conditions = []</code> to
+its BUILD rule. If it fails in the default configuration or in too many
+configurations to list one by one, use <code class="language-plaintext highlighter-rouge">tags = ["manual"]</code> to universally
+disable the test. If the failure is during build instead of test, disable
+part(s) of the build until everything is working again. If possible, ping the
+code’s author / maintainer in your pull request that disables it.</p>
 
 <p>In the case of intermittent failures of unclear origin or which cannot
 reasonably be prevented (for example, network failures of remotely hosted

developers.html

@@ -293,7 +293,7 @@ <h2 id="review-process">Review Process</h2>
     <li>Data files do not count towards the line limit.</li>
     <li>Machine-generated changes do not count towards the line limit.</li>
     <li>Files in
-<a href="/directory_structure.html#dev-directories">Dev Directories</a>
+<a href="/directory_structure.html#experimental-and-dev-directories">Dev Directories</a>
 do not count towards the line limit.</li>
     <li>This rule may be overridden by agreement of at least two platform reviewers
 (listed below).</li>

directory_structure.html

@@ -156,35 +156,55 @@ <h1>Directory Structure</h1>
         <p>The current directory structure in Drake is organized to (1) group functional
 components, (2) limit dependencies, and (3) prevent circular dependencies.</p>
 
-<h1 id="dev-directories">Dev Directories</h1>
+<h1 id="experimental-and-dev-directories">Experimental and Dev Directories</h1>
 
 <p>All code in Drake must adhere to the code standards described in the notes
 <a href="/developers.html#developer-notes">For Developers</a> and must be covered by
-tests, unless the code lives in a subdirectory named <code class="language-plaintext highlighter-rouge">dev</code>.</p>
+tests, unless the code lives in a subdirectory named <code class="language-plaintext highlighter-rouge">experimental</code> or
+<code class="language-plaintext highlighter-rouge">dev</code>.</p>
 
 <p>To promote rapid development of research ideas, experimental code may be placed
-in a subdirectory named <code class="language-plaintext highlighter-rouge">dev</code>.  We do not enforce code standards nor test
-coverage within <code class="language-plaintext highlighter-rouge">dev</code> directories.  For pull requests that affect only
-<code class="language-plaintext highlighter-rouge">dev</code> directories, one feature review is sufficient; platform review is not
-required.  If build or test targets in <code class="language-plaintext highlighter-rouge">dev</code> directories break, the response
-from the on-call build cop will be to disable the offending targets.</p>
-
-<p>The <code class="language-plaintext highlighter-rouge">BUILD.bazel</code> file for <code class="language-plaintext highlighter-rouge">dev</code> directories must live within the directory
-itself, not a parent directory.  (For example, <code class="language-plaintext highlighter-rouge">foo/BUILD.bazel</code> must <strong>not</strong>
-say <code class="language-plaintext highlighter-rouge">srcs = ["dev/bar.cc"],</code>; instead, <code class="language-plaintext highlighter-rouge">foo/dev/BUILD.bazel</code> must exist and
-must say <code class="language-plaintext highlighter-rouge">srcs = ["bar.cc"],</code>.)  This ensures that all <code class="language-plaintext highlighter-rouge">dev</code> code has a
-package name (<code class="language-plaintext highlighter-rouge">//foo/dev</code>) that clearly denotes it as such.</p>
+in a subdirectory named <code class="language-plaintext highlighter-rouge">experimental</code> or <code class="language-plaintext highlighter-rouge">dev</code>. We do not enforce code
+standards nor test coverage within those directories. For pull requests that
+affect only <code class="language-plaintext highlighter-rouge">experimental</code> or <code class="language-plaintext highlighter-rouge">dev</code> directories, one feature review is
+sufficient; platform review is not required.</p>
+
+<p>If build or test targets in <code class="language-plaintext highlighter-rouge">experimental</code> or <code class="language-plaintext highlighter-rouge">dev</code> directories break, the
+response from the on-call build cop will be to disable the offending target(s),
+up to and including removing them from the build (and install) entirely. See
+<a href="/buildcop.html">Build Cop</a> for details.</p>
+
+<p>The <code class="language-plaintext highlighter-rouge">BUILD.bazel</code> file for <code class="language-plaintext highlighter-rouge">experimental</code> and <code class="language-plaintext highlighter-rouge">dev</code> directories must live
+within the directory itself, not a parent directory. (For example,
+<code class="language-plaintext highlighter-rouge">foo/BUILD.bazel</code> must <strong>not</strong> say <code class="language-plaintext highlighter-rouge">srcs = ["experimental/bar.cc"],</code>;
+instead, <code class="language-plaintext highlighter-rouge">foo/experimental/BUILD.bazel</code> must exist and must say
+<code class="language-plaintext highlighter-rouge">srcs = ["bar.cc"],</code>.) This ensures that all <code class="language-plaintext highlighter-rouge">experimental</code> code has a
+package name (<code class="language-plaintext highlighter-rouge">//foo/experimental</code>) that clearly denotes it as such.</p>
+
+<p>Code in <code class="language-plaintext highlighter-rouge">experimental</code> or <code class="language-plaintext highlighter-rouge">dev</code> may only be depended-on by other code in
+such directories. Stable code (outside of <code class="language-plaintext highlighter-rouge">experimental</code> and <code class="language-plaintext highlighter-rouge">dev</code>) must not
+<code class="language-plaintext highlighter-rouge">#include</code> nor <code class="language-plaintext highlighter-rouge">import</code> code from <code class="language-plaintext highlighter-rouge">experimental</code> or <code class="language-plaintext highlighter-rouge">dev</code>.</p>
+
+<p>The distinction between <code class="language-plaintext highlighter-rouge">experimental</code> and <code class="language-plaintext highlighter-rouge">dev</code> is that code in
+<code class="language-plaintext highlighter-rouge">experimental</code> is installed by CMake, packaged as part of our nightly and
+stable release binaries, and has API documentation on our website, but code in
+<code class="language-plaintext highlighter-rouge">dev</code> is neither installed, packaged, nor website-documented. (A corollary is
+that code in <code class="language-plaintext highlighter-rouge">dev</code> cannot have Python bindings. If you need bindings, place
+your code in <code class="language-plaintext highlighter-rouge">experimental</code>, not <code class="language-plaintext highlighter-rouge">dev</code>.)</p>
+
+<p>Code in <code class="language-plaintext highlighter-rouge">experimental</code> must have <code class="language-plaintext highlighter-rouge">experimental</code> as part of its C++ namespace
+and Python module name. It also must not be part of <code class="language-plaintext highlighter-rouge">import pydrake.all</code>.</p>
 
 <h1 id="controlling-dependencies">Controlling Dependencies</h1>
 
-<p>We would like to avoid circular dependencies in the source code tree.  For
+<p>We would like to avoid circular dependencies in the source code tree. For
 example, some code in <code class="language-plaintext highlighter-rouge">drake/systems</code> depends on code in <code class="language-plaintext highlighter-rouge">drake/solvers</code>, so
 code in <code class="language-plaintext highlighter-rouge">drake/solvers</code> should <em>not</em> depend on <code class="language-plaintext highlighter-rouge">drake/systems</code>.</p>
 
 <p>The <code class="language-plaintext highlighter-rouge">drake/examples</code> directories are logically after all of the core libraries
-in <code class="language-plaintext highlighter-rouge">drake</code>.  <code class="language-plaintext highlighter-rouge">test</code> directories located throughout the code are logically
+in <code class="language-plaintext highlighter-rouge">drake</code>. <code class="language-plaintext highlighter-rouge">test</code> directories located throughout the code are logically
 last in the dependency tree – they are allowed to depend on any of the other
-directories.  For example, <code class="language-plaintext highlighter-rouge">test</code> code <strong>is</strong> allowed to use models/code from
+directories. For example, <code class="language-plaintext highlighter-rouge">test</code> code <strong>is</strong> allowed to use models/code from
 the <code class="language-plaintext highlighter-rouge">examples</code> directories to test core functionality, as long as that
 dependency is explicitly declared in the build system rules for that test.</p>