Skip to content

Commit 957332f

Browse files
EricCousineau-TRIEricCousineau-TRI
committed
README: Add information about Drake's fork
1 parent 4a10da9 commit 957332f

File tree

2 files changed

+139
-0
lines changed

2 files changed

+139
-0
lines changed

‎README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,13 @@
11
![pybind11 logo](https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png)
22

3+
## RobotLocomotion Fork for Drake
4+
5+
This is a fork of the [official `pybind/pybind11` repository](https://github.com/pybind/pybind11/). For information specific to this fork, please see
6+
[`README_DRAKE.md`](./README_DRAKE.md).
7+
8+
All the links and badges within this document may link back to the official
9+
repository.
10+
311
# pybind11 — Seamless operability between C++11 and Python
412

513
[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=master)](http://pybind11.readthedocs.org/en/master/?badge=master)

‎README_DRAKE.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# RobotLocomotion Fork of `pybind11` for Drake
2+
3+
This fork is developed for use in [Drake](drake.mit.edu/), and provides the
4+
following features on top of the main development:
5+
6+
* NumPy:
7+
* Incorporates https://github.com/pybind/pybind11/pull/1152 (with fixes):
8+
Permit creating matrices with `dtype=object`.
9+
* Transferring ownership between C++ and Python using `py::wrapper<Class>`
10+
* Resolves https://github.com/pybind/pybind11/issues/1132: Casting from Python to C++ `unique_ptr<Class>`.
11+
* Resolves https://github.com/pybind/pybind11/issues/1145: Transfer of
12+
ownership of subclasse between C++ and Python with `shared_ptr<Class>`
13+
* Resolves https://github.com/pybind/pybind11/issues/1138: Helpful error
14+
message when mixing holder types at runtime.
15+
* Other modifications:
16+
* Resolves https://github.com/pybind/pybind11/issues/1238: Deregister
17+
instances by type and pointer.
18+
19+
For usage in Drake, please see the following pages in Drake:
20+
21+
* [User: Python Bindings](https://drake.mit.edu/python_bindings.html#using-the-python-bindings)
22+
* [Dev: Python Bindings](https://drake.mit.edu/doxygen_cxx/group__python__bindings.html)
23+
* [User: API Reference](https://drake.mit.edu/pydrake/index.html)
24+
25+
## Maintenance Philosophy
26+
27+
This repository should be updated to synchronize with upstream at least every 3
28+
months to ensure that we have core bugfixes and features.
29+
30+
When developing features or bugfixes in this fork that are relevant to upstream
31+
features, first try to make a descriptive upstream issue to see if it is
32+
something desirable for upstream, and make a PR for the community to see and
33+
possibly review. Then continue developing here.
34+
35+
Review should happen using Reviewable.
36+
37+
Please avoid superfluous (non-functional) changes to the original `pybind11`
38+
source code (e.g. no whitespace reflowing), and try to stay relatively close to
39+
`pybind11`s style for consistency.
40+
41+
## Continuous Integration
42+
43+
For simplicity, these checks are copied from upstream's CI which uses Travis
44+
CI as part of GitHub's Checks. They test:
45+
46+
* Ubuntu and macOS
47+
* C++11, C++14, and C++17
48+
* Release and debug builds
49+
* GCC 4.8, 6, and 7
50+
* clang 7
51+
* Apple clang 7.3 and 9
52+
* 64bit and 32bit
53+
* CPython and PyPy
54+
* Python 2.7, 3.5, 3.6, and 3.7
55+
56+
To see builds, see [this fork's Travis CI page](https://travis-ci.com/RobotLocomotion/pybind11/branches).
57+
58+
Windows testing (with AppVeyor) is disabled for this repository.
59+
60+
## Local Git Setup
61+
62+
For development, please make your own GitHub fork of the upstream repository.
63+
64+
It is suggested to clone this repository with the following remotes:
65+
66+
# Clone from upstream.
67+
git clone --origin upstream https://github.com/pybind/pybind11
68+
cd pybind11
69+
git remote set-url --push upstream no_push
70+
# Add robotlocomotion.
71+
git remote add robotlocomotion https://github.com/RobotLocomotion/pybind11
72+
git remote set-url --push robotlocomotion no_push
73+
# Add origin (your fork).
74+
git remote add origin <url-to-your-fork>
75+
# Fetch from all remotes.
76+
git fetch --all
77+
# Checkout to track robotlocomotion/drake.
78+
git checkout -b drake robotlocomotion/drake
79+
80+
## Branches
81+
82+
The following branches are used:
83+
84+
* `drake` - This is the active development branch, forked from `upstream/master`
85+
* `no_prune` - This is now a stale branch, meant to keep track of prior
86+
versions that were rebased. This should be kept for historical purposes.
87+
88+
## Submitting PRs
89+
90+
* Submit your PR to `RobotLocomotion/pybind11` (targeting `drake`) and request
91+
review.
92+
* Ensure that the PR passes the Travis CI checks!
93+
* Submit a PR to Drake using the latest commit from your `pybind11` PR. Ensure
94+
experimental CI passes, and be sure to include macOS. An example of requesting
95+
macOS testing in Drake:
96+
97+
@drake-jenkins-bot mac-mojave-clang-bazel-experimental-release please
98+
@drake-jenkins-bot mac-catalina-clang-bazel-experimental-everything-release please
99+
100+
* Once your PR is reviewed, accepted, and CI passes, merge your
101+
`RobotLocomotion/pybind11` PR, then update your Drake PR to use the latest
102+
merge commit for the fork:
103+
104+
cd pybind11
105+
git fetch robotlocomotion
106+
git rev-parse robotlocomotion/drake
107+
108+
* Merge the Drake PR once it passes CI and review is finished.
109+
110+
## Pulling Upstream Changes
111+
112+
This repository should be merged with upstream (the official repository) about
113+
every 3 months. We use a merge strategy (not rebase) with Git so that updates
114+
can be a simple fast-forward merge.
115+
116+
To update the repository, first checkout the branch and merge:
117+
118+
git fetch robotlocomotion && git fetch upstream
119+
git checkout -b <new-branch-name> robotlocomotion/drake
120+
# Record the soon-to-be-old merge-base.
121+
git merge-base upstream/master robotlocomotion/drake
122+
# Merge.
123+
git merge upstream/master # Resolve conflicts and commit
124+
git push --set-upstream origin <new-branch-name>
125+
126+
Then create a `RobotLocomotion/pybind11` PR with your branch. Title the PR as
127+
`Merge 'upstream/master' (<sha_new>) from previous merge-base (<sha_old>)`,
128+
where `<sha_new>` is the short-form SHA of the current `upstream/master`, and
129+
`<sha_old>` is the short-form SHA of prior merge-base you recorded.
130+
131+
Afterward, follow the normal PR process as outlined above.

0 commit comments

Comments
 (0)