Documentation: RobotLocomotion/drake@b219a6e

Author: drake-jenkins-bot

developers.html

@@ -247,10 +247,7 @@ <h2 id="website-licensing">Website Licensing</h2>
 
   <h1 id="testing">Testing</h1>
 
-  <ul>
-    <li><a href="/unit_testing_instructions.html">Detailed Notes on Drake’s Unit Tests</a></li>
-    <li><a href="/downstream_testing.html">Downstream Testing (Drake as a Dependency)</a></li>
-  </ul>
+  <p>Refer to <a href="/unit_testing_instructions.html">Detailed Notes on Drake’s Unit Tests</a>.</p>
 
   <h1 id="supported-configurations">Supported Configurations</h1>
 
@@ -452,7 +449,7 @@ <h1 id="continuous-integration-notes">Continuous Integration Notes</h1>
 
   <ul>
     <li><a href="https://drake-cdash.csail.mit.edu/index.php?project=Drake">CDash</a></li>
-    <li><a href="/jenkins.html">GitHub PR Interaction with Jenkins</a></li>
+    <li><a href="/jenkins.html">Continuous Integration with GitHub Pull Requests</a></li>
     <li><a href="/buildcop.html">Build Cop</a></li>
   </ul>
 

downstream_testing.html

@@ -155,30 +155,7 @@ <h1>Downstream Testing (Drake as a Dependency)</h1>
   <section class="padding">
     <div class="contain">
       <article class="markdown-body">
-        <h1 id="introduction">Introduction</h1>
-
-<p>To ensure that Drake enables downstream consumption, there are downstream tests
-that show basic usage of Drake as a dependency. Those tests are located in
-the <a href="https://github.com/RobotLocomotion/drake-external-examples">drake-external-examples</a>
-repository.</p>
-
-<h1 id="continuous-integration">Continuous Integration</h1>
-
-<p>Please see the drake-external-examples <a href="https://github.com/RobotLocomotion/drake-external-examples#continuous-integration">Continuous Integration</a>
-section.</p>
-
-<h1 id="local-testing">Local Testing</h1>
-
-<p>For CMake, see the
-<a href="https://github.com/RobotLocomotion/drake-external-examples/tree/master/drake_cmake_installed#developer-testing">drake_cmake_installed</a>
-example.</p>
-
-<p>For Bazel, see the
-<a href="https://github.com/RobotLocomotion/drake-external-examples/tree/master/drake_bazel_external">drake_bazel_external</a>
-example, and note the comment in
-<a href="https://github.com/RobotLocomotion/drake-external-examples/blob/master/drake_bazel_external/WORKSPACE">WORKSPACE</a>
-which mentions using something like
-<a href="https://docs.bazel.build/versions/master/be/workspace.html#local_repository">local_repository</a> to consume a local checkout of Drake.</p>
+        <p>Content moved to <a href="/jenkins.html#testing-via-external-examples">Continuous Integration with GitHub Pull Requests</a>.</p>
 
       </article>
     </div>

installation.html

@@ -229,7 +229,7 @@ <h2 id="supported-configurations">Supported Configurations</h2>
 <p>⁽³⁾ The Python version shown in the table is supported for all installation
 channels. Additionally, when installing via <code class="language-plaintext highlighter-rouge">pip</code>
 on Ubuntu Python versions 3.10 through 3.13 (inclusive) are supported and
-on macOS Python versions 3.11 through 3.13 (inclusive) are supported.
+on macOS Python versions 3.12 through 3.13 (inclusive) are supported.
 Refer to <a href="/stable.html#os-support">OS Support</a> for details on our “end of life”
 timeline for changing which Python versions are supported.</p>
 

jenkins.html

@@ -8,7 +8,7 @@
     <link rel="manifest" type="application/manifest+json" href="/site.webmanifest"/>
     <link rel="mask-icon" type="image/svg+xml" href="/mask-icon.svg" color="#990000"/>
     <link rel="shortcut icon" type="image/png" href="/favicon.png"/>
-    <title>Drake: GitHub PR Interaction with Jenkins</title>
+    <title>Drake: Continuous Integration with GitHub Pull Requests</title>
     <meta
       name="description"
       content="Drake (&quot;dragon&quot; in Middle English) is a C++ toolbox started by the Robot
@@ -149,7 +149,7 @@
         <div class="drake-page">
   <header class="drake-page-header">
     <div class="contain">
-      <h1>GitHub PR Interaction with Jenkins</h1>
+      <h1>Continuous Integration with GitHub Pull Requests</h1>
     </div>
   </header>
   <section class="padding">
@@ -356,6 +356,76 @@ <h3 id="wheel">Wheel</h3>
 <span class="nb">source env</span>/bin/activate
 </code></pre></div></div>
 
+<h1 id="testing-via-external-examples">Testing via External Examples</h1>
+
+<p>The examples within Drake’s
+<a href="https://github.com/RobotLocomotion/drake-external-examples">gallery of external examples</a>
+provide continuous integration via both Jenkins and GitHub Actions. This provides
+downstream test coverage for Drake developers to ensure reliability in the
+build infrastructure. Additionally, the GitHub Actions provide a benefit
+for end users, in that examples of CI pipelines on public servers for
+external projects using Drake installations are made easily accessible.</p>
+
+<p>See the external examples
+<a href="https://github.com/RobotLocomotion/drake-external-examples#continuous-integration">continuous integration</a>
+for details on which examples use Jenkins or GitHub Actions. In general,
+GitHub Actions is used for the lightweight examples which use some
+installed version of Drake, while Jenkins is used for complete coverage
+on examples which pull in Drake externally and build it.</p>
+
+<p>When a new pull request is opened in Drake, members of the RobotLocomotion
+organization can utilize Jenkins and GitHub Actions to run custom builds.
+This is especially pertinent for pull requests which affect the build infrastructure.</p>
+
+<h2 id="jenkins">Jenkins</h2>
+
+<p>To test the examples which use Jenkins for CI with a PR branch of Drake,
+comment on an open pull request using the following command:</p>
+
+<ul>
+  <li><code class="language-plaintext highlighter-rouge">@drake-jenkins-bot linux-jammy-unprovisioned-external-examples please</code></li>
+</ul>
+
+<p>or follow the <a href="#scheduling-builds-via-the-jenkins-user-interface">instructions above</a>
+to schedule a build of the
+<a href="https://drake-jenkins.csail.mit.edu/view/Linux%20Jammy%20Unprovisioned/job/linux-jammy-unprovisioned-external-examples/">external examples job</a>.
+Note that this job provides parameters for branches of
+drake and drake-external-examples.</p>
+
+<h2 id="github-actions">GitHub Actions</h2>
+
+<p>You can schedule “experimental” builds of a <a href="/from_binary.html">binary package</a>,
+<a href="/apt.html">debian package</a>, and/or a <a href="/pip.html">wheel package</a> by following the
+instructions <a href="#building-packages-on-demand">above</a>.
+Copy the download URL(s) obtained from the build as described.</p>
+
+<p>From the <a href="https://github.com/RobotLocomotion/drake-external-examples/actions/workflows/ci.yml">GitHub Actions workflow</a>
+in drake-external-examples, notice the message “This workflow has a
+<code class="language-plaintext highlighter-rouge">workflow_dispatch</code> event trigger.” Click “Run workflow” and input the
+download URL(s) copied from Jenkins in the drop-down menu.
+All parameters are optional, so you can ignore the package(s) and/or platform(s)
+that you don’t need. (For those left blank, the default workflow will run using
+a more “stable” version of Drake, which is usually either source code from
+<code class="language-plaintext highlighter-rouge">master</code> or a nightly release depending on the example).</p>
+
+<h2 id="local-testing">Local Testing</h2>
+
+<p>For CMake, see the
+<a href="https://github.com/RobotLocomotion/drake-external-examples/tree/main/drake_cmake_installed#developer-testing">drake_cmake_installed</a>
+example.</p>
+
+<p>For Bazel, see the
+<a href="https://github.com/RobotLocomotion/drake-external-examples/tree/main/drake_bazel_external">drake_bazel_external</a>
+example, and note the comments in:</p>
+
+<ul>
+  <li>the <a href="https://github.com/RobotLocomotion/drake-external-examples/blob/main/drake_bazel_external#using-a-local-checkout-of-Drake">README</a>,
+which mentions using
+<a href="https://bazel.build/reference/command-line-reference#flag--override_module"><code class="language-plaintext highlighter-rouge">--override-module</code></a> to consume a local checkout of Drake</li>
+  <li><a href="https://github.com/RobotLocomotion/drake-external-examples/blob/main/drake_bazel_external/MODULE.bazel"><code class="language-plaintext highlighter-rouge">MODULE.bazel</code></a>,
+which can be modified to use a particular revision (commit or release) of Drake</li>
+</ul>
+
       </article>
     </div>
   </section>

release_notes/end_of_support.html

@@ -254,7 +254,8 @@ <h1 id="wheel-packages">Wheel packages</h1>
   <li>Python 3.11 (Wheel)
     <ul>
       <li>On Linux, Drake still supports Python 3.11 wheels.</li>
-      <li>On macOS arm64, Drake still supports Python 3.11 wheels.</li>
+      <li>On macOS arm64, the last version with support for Python 3.11 wheels was
+<a href="https://github.com/RobotLocomotion/drake/releases/tag/v1.40.0">v1.40.0</a>.</li>
       <li>On macOS x86_64, the last version with support for Python 3.11 wheels was
 <a href="https://github.com/RobotLocomotion/drake/releases/tag/v1.34.0">v1.34.0</a>.</li>
     </ul>

release_playbook.html

@@ -196,6 +196,8 @@ <h2 id="prior-to-release">Prior to release</h2>
       <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.
@@ -337,8 +339,6 @@ <h2 id="cutting-the-release">Cutting the release</h2>
       <li>There is a dummy date 2099-12-31 nearby that should likewise be changed.</li>
       <li>Make sure that the nightly build git sha from the prior steps matches the
 <code class="language-plaintext highlighter-rouge">newest_commit</code> whose changes are enumerated in the notes.</li>
-      <li>Update the github links within <code class="language-plaintext highlighter-rouge">doc/_pages/from_binary.md</code> to reflect
-the upcoming v1.N.0.</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>
@@ -381,13 +381,13 @@ <h2 id="cutting-the-release">Cutting the release</h2>
         </ul>
       </li>
       <li>Click the box labeled “Attach binaries by dropping them here or selecting
-them.” and then choose for upload the <strong>36</strong> release files from
+them.” and then choose for upload the <strong>33</strong> release files from
 <code class="language-plaintext highlighter-rouge">/tmp/drake-release/v1.N.0/...</code>:
         <ul>
           <li>9: 3 <code class="language-plaintext highlighter-rouge">.tar.gz</code> + 6 checksums</li>
           <li>6: 2 <code class="language-plaintext highlighter-rouge">.deb</code> + 4 checksums</li>
           <li>12: 4 linux <code class="language-plaintext highlighter-rouge">.whl</code> + 8 checksums</li>
-          <li>9: 3 macOS arm <code class="language-plaintext highlighter-rouge">.whl</code> + 6 checksums</li>
+          <li>6: 2 macOS arm <code class="language-plaintext highlighter-rouge">.whl</code> + 4 checksums</li>
           <li>Note that on Jammy with <code class="language-plaintext highlighter-rouge">snap</code> provided Firefox, drag-and-drop from
 Nautilus will fail, and drop all of your release page inputs typed so
 far. Use the Firefox-provided selection dialog instead, by clicking on
@@ -425,16 +425,23 @@ <h2 id="post-release-wheel-upload">Post-release wheel upload</h2>
 <code class="language-plaintext highlighter-rouge">twine</code> uploader. See <a href="https://pypi.org/help/#apitoken">https://pypi.org/help/#apitoken</a> and <a href="https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#create-an-account">https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#create-an-account</a>
 for advice on managing api tokens.</p>
 
-<p>For Jammy (and later?), <code class="language-plaintext highlighter-rouge">apt install twine</code> gives a perfectly adequate
-version of <code class="language-plaintext highlighter-rouge">twine</code>.</p>
+<p>For Jammy, <code class="language-plaintext highlighter-rouge">apt install twine</code> is too old. Instead, you must run it from a
+venv (detail below).</p>
 
 <ol>
   <li>
     <p>Run <code class="language-plaintext highlighter-rouge">twine</code> to upload the wheel release, as follows:</p>
 
     <ol>
       <li>You will need your PyPI username and password for this. (Do not use drake-robot.)</li>
-      <li>Run <code class="language-plaintext highlighter-rouge">twine upload /tmp/drake-release/v1.N.0/*.whl</code>.</li>
+      <li>Run:
+        <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ cd tmp
+$ python3 -m venv env
+$ env/bin/pip install twine
+$ env/bin/twine upload /tmp/drake-release/v1.N.0/*.whl
+$ rm -rf env
+</code></pre></div>        </div>
+      </li>
       <li>Confirm that all of the uploads succeeded without any error messages in
 your terminal.</li>
     </ol>