Documentation: RobotLocomotion/drake@52872ff

Author: drake-jenkins-bot

jenkins.html

@@ -374,6 +374,16 @@ <h3 id="wheel">Wheel</h3>
 <span class="nb">source env</span>/bin/activate
 </code></pre></div></div>
 
+<h1 id="disabling-builds-on-pull-requests">Disabling Builds on Pull Requests</h1>
+
+<p>For draft pull requests that may have frequent updates to the remote branch,
+it can be useful to disable the builds that run automatically. This can be done
+by adding the label <code class="language-plaintext highlighter-rouge">status: defer ci</code>. Jobs will automatically be reported
+back to the pull request as failures, but won’t run the actual build. Since
+these jobs are required to merge, this label will eventually need to be removed.
+Comment <code class="language-plaintext highlighter-rouge">@drake-jenkins-bot retest this please</code> after removing the label to
+trigger a re-run.</p>
+
 <h1 id="testing-via-external-examples">Testing via External Examples</h1>
 
 <p>The examples within Drake’s

release_playbook.html

@@ -176,39 +176,33 @@ <h2 id="prior-to-release">Prior to release</h2>
   <li>Choose the next version number.</li>
   <li>Create a local Drake branch named <code class="language-plaintext highlighter-rouge">release_notes-v1.N.0</code> (so that others
 can easily find and push to it after the PR is opened).</li>
-  <li>As the first commit on the branch, mimic the commit
-<a href="https://github.com/RobotLocomotion/drake/commit/cb6f616ced5496ea7863db46d86551930c9d61f7"><code class="language-plaintext highlighter-rouge">drake@cb6f616ced</code></a>
-in order to disable CI.  A quick way to do this might be:
-    <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git fetch upstream cb6f616ced5496ea7863db46d86551930c9d61f7
-git cherry-pick FETCH_HEAD
-</code></pre></div>    </div>
+  <li>Bootstrap the release notes file using the
+<code class="language-plaintext highlighter-rouge">tools/release_engineering/relnotes</code> tooling, with <code class="language-plaintext highlighter-rouge">--action=create</code>
+for the first run. Instructions can be found atop its source code:
+<a href="https://github.com/RobotLocomotion/drake/blob/master/tools/release_engineering/relnotes.py"><code class="language-plaintext highlighter-rouge">relnotes.py</code></a>.
+    <ul>
+      <li>The output is draft release notes in <code class="language-plaintext highlighter-rouge">doc/_release-notes/v1.N.0.md</code>.</li>
+      <li>The version numbers in <code class="language-plaintext highlighter-rouge">doc/_pages/from_binary.md</code> should also have
+   been automatically upgraded.
+Commit the results.</li>
+    </ul>
   </li>
   <li>Push that branch and then open a new pull request titled:
     <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>[doc] Add release notes v1.N.0
 </code></pre></div>    </div>
     <p>Make sure that “Allow edits by maintainers” on the GitHub PR page is
-enabled (the checkbox is checked). Set label <code class="language-plaintext highlighter-rouge">release notes: none</code>.</p>
+enabled (the checkbox is checked). Set the labels <code class="language-plaintext highlighter-rouge">release notes: none</code>
+and <code class="language-plaintext highlighter-rouge">status: defer ci</code> to disable CI while notes-only updates are ongoing.</p>
   </li>
-  <li>For release notes, on an ongoing basis, add recent commit messages to the
-release notes draft using the <code class="language-plaintext highlighter-rouge">tools/release_engineering/relnotes</code> tooling.
-(Instructions can be found atop its source code: <a href="https://github.com/RobotLocomotion/drake/blob/master/tools/release_engineering/relnotes.py"><code class="language-plaintext highlighter-rouge">relnotes.py</code></a>)
-    <ol>
-      <li>On the first run, use <code class="language-plaintext highlighter-rouge">--action=create</code> to bootstrap the file.
-        <ul>
-          <li>The output is draft release notes in <code class="language-plaintext highlighter-rouge">doc/_release-notes/v1.N.0.md</code>.</li>
-          <li>The version numbers in <code class="language-plaintext highlighter-rouge">doc/_pages/from_binary.md</code> should also have
-been automatically upgraded.</li>
-        </ul>
-      </li>
-      <li>On the subsequent runs, use <code class="language-plaintext highlighter-rouge">--action=update</code> to refresh the file.
-        <ul>
-          <li>Try to avoid updating the release notes to refer to changes newer than
+  <li>Make gradual updates to the release notes using
+  <code class="language-plaintext highlighter-rouge">tools/release_engineering/relnotes</code>, with <code class="language-plaintext highlighter-rouge">--action=update</code> to
+  refresh the file.
+    <ul>
+      <li>Try to avoid updating the release notes to refer to changes newer than
 the likely release, i.e., if you run <code class="language-plaintext highlighter-rouge">--update</code> on the morning you’re
 actually doing the release, be sure to pass the <code class="language-plaintext highlighter-rouge">--target_commit=</code>
 argument to avoid including commits that will not be part of the tag.</li>
-        </ul>
-      </li>
-    </ol>
+    </ul>
   </li>
   <li>For release notes, on an ongoing basis, clean up and relocate the commit
 notes to properly organized and wordsmithed bullet points. See <a href="#polishing-the-release-notes">Polishing
@@ -220,11 +214,11 @@ <h2 id="prior-to-release">Prior to release</h2>
   <li>As the release is nearly ready, post a call for action for feature teams to
 look at the draft document and provide suggestions (in reviewable) or fixes
 (as pushes).
-    <ol>
+    <ul>
       <li>To help ensure that the “newly deprecated APIs” section is accurate, grep
 the code for <code class="language-plaintext highlighter-rouge">YYYY-MM-01</code> deprecation notations, for the <code class="language-plaintext highlighter-rouge">MM</code> values
 that would have been associated with our +3 months typical period.</li>
-    </ol>
+    </ul>
   </li>
 </ol>
 
@@ -341,7 +335,8 @@ <h2 id="cutting-the-release">Cutting the release</h2>
 <code class="language-plaintext highlighter-rouge">newest_commit</code> whose changes are enumerated in the notes.</li>
     </ol>
   </li>
-  <li>Re-enable CI by reverting the commit you added way up above in step 3 of <strong>Prior to release</strong>.</li>
+  <li>Re-enable CI by removing the label <code class="language-plaintext highlighter-rouge">status: defer ci</code> and commenting
+<code class="language-plaintext highlighter-rouge">@drake-jenkins-bot retest this please</code> to trigger a re-run.</li>
   <li>Wait for the wheel builds to complete, and then download release artifacts:
     <ol>
       <li>Use the