-
Notifications
You must be signed in to change notification settings - Fork 6
/
stable.html
439 lines (352 loc) · 20.3 KB
/
stable.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta name="msapplication-config" content="/browserconfig.xml"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta charset="utf-8"/>
<link rel="apple-touch-icon" type="image/png" href="/apple-touch-icon.png"/>
<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: Drake Stability Guidelines</title>
<meta
name="description"
content="Drake ("dragon" in Middle English) is a C++ toolbox started by the Robot
Locomotion Group at the MIT Computer Science and Artificial Intelligence
Lab (CSAIL). The development team has now grown significantly, with core
development led by the Toyota Research Institute. It is a collection of
tools for analyzing the dynamics of our robots and building control
systems for them, with a heavy emphasis on optimization-based design/
analysis.
"/>
<!--
The "Work Sans" font is licensed under the SIL Open Font License (OFL). For
more information, see:
- https://fonts.google.com/specimen/Work+Sans?preview.text_type=custom#about
- https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL
-->
<link href="https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=Work+Sans:wght@300;400;600;700;800&display=swap" rel="stylesheet"/>
<link rel="stylesheet" href="/third_party/github-styling/github-markdown.css"/>
<link rel="stylesheet" href="/third_party/dracula/syntax.css"/>
<link rel="stylesheet" href="/third_party/pylons/pylons.css"/>
<link rel="stylesheet" href="/assets/css/main.css"/>
</head>
<body>
<header class="site-header">
<div class="site-header-inner contain">
<a href="/" class="drake-logo">
<img src="/images/drake-logo-white.svg">
</a>
<div class="menu-mobile-toggle">
<span></span>
</div>
<nav class="site-menu">
<ul>
<li class="site-menu-item site-menu-item-main">
<a href="/" class="site-menu-item">Home</a>
</li>
<li class="site-menu-item site-menu-item-main">
<a href="/installation.html" class="site-menu-item">Installation</a>
</li>
<li class="site-menu-item site-menu-item-main">
<a href="/gallery.html" class="site-menu-item">Gallery</a>
</li>
<li class="site-menu-item site-menu-item-main">
API Documentation
<div class="sub">
<a href="/doxygen_cxx/index.html" class="site-menu-item">C++</a>
<a href="/pydrake/index.html" class="site-menu-item">Python</a>
</div>
</li>
<li class="site-menu-item site-menu-item-main">
Resources
<div class="sub">
<a href="/getting_help.html" class="site-menu-item">Getting Help</a>
<a href="https://deepnote.com/workspace/Drake-0b3b2c53-a7ad-441b-80f8-bf8350752305/project/Tutorials-2b4fc509-aef2-417d-a40d-6071dfed9199/%2Findex.ipynb" class="site-menu-item">Tutorials</a>
<a href="/python_bindings.html" class="site-menu-item">Python Bindings</a>
<a href="/developers.html" class="site-menu-item">For Developers</a>
<a href="/credits.html" class="site-menu-item">Credits</a>
</div>
</li>
<li class="search">
<div class="search-icon">
<!-- This is an inline SVG image of a magnifying glass. -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 374.9 374.84">
<path d="M235 270a148.74 148.74 0 1 1 35-35l97.74 97.74a24.37 24.37 0 0 1 0 34.58l-.4.4a24.47 24.47 0 0 1-34.58 0L235 270Zm-86.22-7.47A113.75 113.75 0 1 0 35 148.75 113.75 113.75 0 0 0 148.75 262.5Z"/>
</svg>
</div>
<div class="search-bar">
<form id="search_form" action="https://google.com/search" method="get">
<input type="text" name="q" placeholder="Search all of Drake…" />
<input type="hidden" name="q" value="site:drake.mit.edu OR site:underactuated.csail.mit.edu OR site:manipulation.csail.mit.edu" />
</form>
<div class="search-close">
<!-- This is an inline SVG image of an "X". -->
<svg height="20" width="20" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 373.61 373.57">
<path d="M219.71 186.77 366.71 40a23.43 23.43 0 1 0-33.13-33.13l-146.77 147-146.77-147A23.43 23.43 0 0 0 6.9 40l147 146.77-147 146.77a23.43 23.43 0 1 0 33.14 33.13l146.77-147 146.77 147a23.43 23.43 0 1 0 33.13-33.13Z"/>
</svg>
</div>
</div>
<ul id="results-container"></ul>
</li>
<li class="github-link">
<a href="https://github.com/RobotLocomotion/drake" class="site-menu-item">GitHub <img src="/third_party/images/GitHub-Mark-Light-64px.png" /></a>
</li>
</ul>
</nav>
</div>
</header>
<div class="page">
<div class="content">
<div class="drake-page">
<header class="drake-page-header">
<div class="contain">
<h1>Drake Stability Guidelines</h1>
</div>
</header>
<section class="padding">
<div class="contain">
<article class="markdown-body">
<p>We want to move fast and bring out exciting new ideas quickly. We also
appreciate users’ need for a solid, stable foundation to build on. This
document explains what kind of stability the Drake project aims to provide,
and what you can do to minimize the impact of the inevitable changes to Drake
on your own work.</p>
<h1 id="rolling-releases">Rolling releases</h1>
<p>Drake ships a new stable version approximately once per month. The versions are
numbered “1.x.y”, where “x” increases by one for each stable version, and “y”
reflects the patch version (typically zero). Drake does <strong>not</strong> follow
<a href="https://semver.org/">SemVer</a>. Instead, we use a rolling deprecation window.
In each release, new deprecations might be announced, and then those changes
will be finalized 3+ minor versions later, without changing the major version
number.</p>
<p>Deprecation announcements appear in the
<a href="/release_notes/release_notes.html">release notes</a> for each stable release.
For C++ and Python API changes, we will also use the language mechanism to
highlight the change when possible (<code class="language-plaintext highlighter-rouge">[[deprecated]]</code> for C++; <code class="language-plaintext highlighter-rouge">warnings.warn</code>
for Python). However, those mechanisms will not always trigger in every case,
and some deprecations will reach beyond what those tools can denote.
Therefore, we still recommend that you monitor the release notes as the final
arbiter of deprecation announcements.</p>
<p>Due to our 3-month announcement window, we recommend upgrading your pinned
version of Drake at least that frequently. If you wish to upgrade less
frequently, you still might benefit from rolling forward a few minor versions
at a time, in order to obtain the built-in C++ and Python deprecation
suggestions to guide you.</p>
<p>In general, we do not plan to backport fixes into prior stable releases.</p>
<h1 id="stable-api">Stable API</h1>
<p>We define a large portion of Drake as our “Stable API” that you can rely
on. For the Stable API, we aim to give at least 3 months of notice ahead of any
disruption (via deprecation announcements in Drake’s
<a href="/release_notes/release_notes.html">release notes</a>, and with compile-time or
run-time warnings when feasible). Any element of Drake that is not explicitly
documented to be part of the Stable API is deemed “unstable” and is subject to
change or removal without prior notice.</p>
<p>The sub-headings below explain the Stable API for various facets of Drake.</p>
<p>Specific code or tools beyond what is listed here can also opt-in to be part of
the Stable API in its local documentation. Those opt-ins are not enumerated
here.</p>
<p>On very rare occasions it is impractical, too expensive, or logically unsound
to meet the full three month deprecation window. In these cases the change will
be announced in the “Breaking changes” section of the release notes.</p>
<h2 id="c">C++</h2>
<p>The C++ Stable API covers all C++ library code within <code class="language-plaintext highlighter-rouge">namespace drake</code> whose
header files are distributed in a
<a href="/from_binary.html#stable-releases">Drake pre-compiled binary image</a>.</p>
<ul>
<li>Excluding the <code class="language-plaintext highlighter-rouge">drake/examples/...</code> directory tree.</li>
<li>Excluding code within <code class="language-plaintext highlighter-rouge">namespace internal</code>.</li>
<li>Excluding code documented as “internal use only”.</li>
<li>Excluding code documented with an “experimental” warning.</li>
</ul>
<p>In particular, note that any
<a href="https://drake.mit.edu/directory_structure.html">directory named “dev”</a>
is necessarily excluded, because its header files are not installed.</p>
<h2 id="python">Python</h2>
<p>The Python Stable API covers all Python library code under <code class="language-plaintext highlighter-rouge">import drake</code> or
<code class="language-plaintext highlighter-rouge">import pydrake</code> that is distributed in a
<a href="/pip.html#stable-releases">Drake PyPI wheel</a>:</p>
<ul>
<li>Excluding the <code class="language-plaintext highlighter-rouge">pydrake.examples...</code> module tree.</li>
<li>Excluding names that begin with a leading underscore, which denotes “internal
use only” by convention of
<a href="https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles">PEP-8</a>.</li>
<li>Excluding code documented as “internal use only”.</li>
<li>Excluding code documented with an “experimental” warning.</li>
<li>Excluding the “all” modules such as <code class="language-plaintext highlighter-rouge">pydrake.all</code>, <code class="language-plaintext highlighter-rouge">pydrake.systems.all</code>,
etc. These are intended to be shortcuts for temporary hacking only, and so
are not Stable.
<ul>
<li>However, the existence of the <code class="language-plaintext highlighter-rouge">pydrake.all</code> module is part of the Stable
API (we will not remove it without notice), but the specific list of items
contained within it is not Stable.</li>
</ul>
</li>
</ul>
<h2 id="build-system">Build system</h2>
<p>The Bazel Stable API covers all Drake Bazel targets (e.g., <code class="language-plaintext highlighter-rouge">@drake//common</code>)
with public visibility that refer to C++ or Python library code that is itself
part of the “Stable API”:</p>
<ul>
<li>This <strong>includes</strong>
<a href="https://docs.bazel.build/versions/main/build-ref.html#dependencies">depending on</a>
those labels (e.g., <code class="language-plaintext highlighter-rouge">deps = ["@drake//common"]</code>).</li>
<li>This <strong>excludes</strong>
<a href="https://docs.bazel.build/versions/main/build-ref.html#load">loading</a>
Drake’s bzl macros (e.g., <code class="language-plaintext highlighter-rouge">load("@drake//foo:bar.bzl", "bar_macro")</code>.</li>
</ul>
<p>For Drake’s dependencies:</p>
<ul>
<li>The <code class="language-plaintext highlighter-rouge">add_default_...</code> macros defined in <code class="language-plaintext highlighter-rouge">@drake//tools/workspace:default.bzl</code>
are all part of the Stable API.
<ul>
<li>For any Bazel external loaded by these functions (e.g., <code class="language-plaintext highlighter-rouge">"@eigen"</code>), we
will deprecate it prior to removing our definition of the dependency.
<ul>
<li>Excluding any items documented as “internal use only”.</li>
<li>Excluding any items documented with an “experimental” warning.</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>We may upgrade any of our dependencies to a newer version without prior notice.
If you require an older version, you will need to rebuild Drake from source and
pin your own WORKSPACE to refer to the older version of the dependency.</p>
<p>We may add new dependencies without prior notice. All of our dependencies will
either be installed via the host system via our <code class="language-plaintext highlighter-rouge">install_prereqs</code> scripts,
and/or downloaded at build-time via our <code class="language-plaintext highlighter-rouge">add_default_...</code> macros, and/or
specified via packaging metadata in the case of <code class="language-plaintext highlighter-rouge">apt</code> or <code class="language-plaintext highlighter-rouge">pip</code>.</p>
<h2 id="lcm-messages">LCM messages</h2>
<p>Our Stable API covers all of Drake’s
<a href="https://github.com/RobotLocomotion/drake/tree/master/lcmtypes">LCM message definitions</a>:</p>
<ul>
<li>Excluding messages with “internal” as part of the message name.</li>
<li>Excluding messages with “experimental” as part of the message name.</li>
<li>Excluding messages documented as “internal use only”.</li>
<li>Excluding messages documented as “experimental”.</li>
</ul>
<p>Regarding changes to message definitions:</p>
<ul>
<li>LCM messages provide no mechanism for schema evolution or versioning.</li>
<li>If we need to change a message definition (e.g., <code class="language-plaintext highlighter-rouge">lcmt_schunk_wsg_command</code>),
we will fork it into a newly-named <code class="language-plaintext highlighter-rouge">lcmt_schunk_wsg_command2</code> with the
change, and deprecate the original <code class="language-plaintext highlighter-rouge">lcmt_schunk_wsg_command</code>.</li>
<li>Drake code that uses that message type (e.g., <code class="language-plaintext highlighter-rouge">SchunkWsgCommandSender</code>) will
immediately switch to use the revised message, without deprecation.</li>
<li>This means that independent, direct use of the LCM message by users will have
a smooth transition like any other library code, but any dependency on
Drake’s sending or receiving a particular schema is not part of our “Stable
API” promise.</li>
</ul>
<h2 id="behavioral-changes">Behavioral changes</h2>
<p>Even if Drake does not change its API, sometimes its implementation may evolve
in ways that affect your use. In the limit,
<a href="https://xkcd.com/1172/">any implementation change can be a breaking change</a>.</p>
<p>Our goal is to keep our implementation within its documented API promises
(<a href="https://drake.mit.edu/doxygen_cxx/">C++</a>,
<a href="https://drake.mit.edu/pydrake/">Python</a>).
Any significant changes to the API documentation should be announced via
deprecation with 3 months of advance notice.</p>
<p>Sometimes our software will choose a default value when nothing more specific
is provided. Those defaults may change as we find better heuristics, without
prior notice. Similarly, our numerical algorithms may change in ways that alter
the calculated results. There is no guarantee that Drake’s output is
bitwise-identical from one version to the next.</p>
<h2 id="exemptions">Exemptions</h2>
<p>Any new API will have these requirements waived for the first version where
that API appears. (In other words, the second release of the API is the one
where the Stable guarantees come into effect.) However, we will make a best
effort to adhere to these guidelines as we resolve any issues with the new API,
even in the first release.</p>
<p>Drake’s nightly builds are exempt from any stability guarantees.</p>
<p>Within the Stable API, we also expect you to meet certain requirements in order
to obtain the stability guarantee:</p>
<ul>
<li>Include what you use.
<ul>
<li>Drake’s <code class="language-plaintext highlighter-rouge">#include</code> graph will change over time; always <code class="language-plaintext highlighter-rouge">#include</code> the
header that matches each Drake class that you use.</li>
<li>Relatedly, do not include headers that you don’t use. Our C++ or Python
deprecation warnings typically only trigger on <strong>call</strong> into the API, not
mere inclusion or importing.</li>
</ul>
</li>
<li>For Bazel users, <code class="language-plaintext highlighter-rouge">deps</code> what you use.
<ul>
<li>Drake’s <code class="language-plaintext highlighter-rouge">deps</code> graph will change over time; always list out your Drake
library dependencies (to match what you <code class="language-plaintext highlighter-rouge">#include</code> or <code class="language-plaintext highlighter-rouge">import</code>); do not rely
on transitive dependencies to bring them in.</li>
</ul>
</li>
<li>In C++, do not forward-declare anything from Drake.</li>
<li>In C++, do not depend on the exact signature of Drake functions, as we may
add new, defaulted arguments without prior notice (i.e., do not take the
address of any Drake function, or assign it to a <code class="language-plaintext highlighter-rouge">std::function</code>).</li>
<li>In C++, do not depend on the exact order of <code class="language-plaintext highlighter-rouge">struct</code> fields.
While the <em>relative</em> order of struct fields is guaranteed, new member fields
might be inserted between existing fields. Consequently, when using
<a href="https://en.cppreference.com/w/cpp/language/aggregate_initialization">aggregate initialization</a>
always use designated initializers (i.e., field names) when referring to
struct fields.</li>
</ul>
<h3 id="model-files">Model files</h3>
<p>Note in particular that any data files provided by Drake (e.g., SDFormat or
URDF models) are not incorporated into the “Stable API”, even though some of
those files are distributed in our stable releases for demonstration
purposes. We may alter the models (e.g., changing the collision geometry or
joint limits) or remove a model entirely, without prior notice.</p>
<h1 id="abi">ABI</h1>
<p>Drake does not offer any stable ABI
(<a href="https://en.wikipedia.org/wiki/Application_binary_interface">Application Binary Interface</a>).
We expect any C++ code linked against Drake within the same program to use the
identical source revision and build flags of Drake as all other code within
that program.</p>
<p>Refer to <a href="/installation.html">Installation and Quickstart</a> for the current
details.</p>
<h1 id="os-support">OS Support</h1>
<p>Drake intends to support the two most recent versions of Ubuntu LTS and macOS
on an ongoing basis. That generally means that your OS must be no more than
~2-4 years old for Ubuntu, or ~2 years old for macOS.</p>
<p>On Ubuntu, Drake only intends to support Ubuntu’s default version of Python (at
<code class="language-plaintext highlighter-rouge">/usr/bin/python3</code>), except when installing from pip in which case any newer
version is also intended to be supported. This is consistent with
<a href="https://numpy.org/neps/nep-0029-deprecation_policy.html">NEP-29</a>.</p>
<p>On macOS, Drake only intends to support the one newest version of Python
available via Homebrew.
See <a href="https://github.com/RobotLocomotion/drake/issues/18791">#18791</a> for a
discussion of possible improvements.</p>
<p>Refer to <a href="/installation.html">Installation and Quickstart</a> for the current
details.</p>
</article>
</div>
</section>
</div>
<footer class="site-footer padding">
<div class="contain">
<a href="/" class="drake-logo">
<img src="/images/drake-logo.svg">
</a>
<div class="footer-menu">
<ul>
<li>
<a href="/doxygen_cxx/index.html" class="site-menu-item">C++</a>
</li>
<li>
<a href="/pydrake/index.html" class="site-menu-item">Python</a>
</li>
<li class="github-link">
<a href="https://github.com/RobotLocomotion/drake" class="site-menu-item">GitHub <img src="/third_party/images/GitHub-Mark-64px.png" /></a>
</li>
</ul>
</div>
</div>
<!-- TODO(eric.cousineau): Consider placing copyright here. -->
</footer>
</div>
</div>
<script src="/assets/js/mobile.js"></script>
<!-- Search -->
<script src="/assets/js/search.js"></script>
</body>
</html>