We want to make contributing to this project as easy and transparent as possible.
idb
is formed of an Objective-C++ server (the "companion") and a python client.
There's a number of goals that we had in mind when building this out:
- The companion is not optimized for APIs that are convenient for users to use, we're optimizing for making it as easy as possible to use with an RPC framework.
- As much of the core functionality of dealing with Simulators and Devices is pushed down into the
FBSimulatorControl
andFBDeviceControl
projects. This means that the companion is as simple as possible and that we build sane and easy-to-use Objective-C APIs. FBSimulatorControl
andFBDeviceControl
are pure Objective-C. This makes interop with Swift as easy as possible.FBSimulatorControl
andFBDeviceControl
projects vend their public API via protocols onFBSimulator
andFBDevice
instances. These APIs should exposeFBFuture
instances so that they can operate asynchronously and propogate errors.- The companion server into the APIs of the above and performs the neccessary coercions between Objective-C data models and gRPC's Protocol Buffers.
- Any rpc that is:
- Long Lived (e.g.
instruments
) - Provides incremental output (e.g.
log
) - Pushes large amounts of data between the client/server.
Should use streaming gRPC calls. This means that
idb
can be as responsive and performant as possible.
- Long Lived (e.g.
idb
client calls are in modules underipc
. The name of the module is the name of the call. The calls are then dynamically attached to the client object. The reasoning behind this is it prevents bloat in the client class and makes testing of individual client commands far easier.- The command line interface to python client calls should perform as little work as possible, other than calling the python client API.
idb
does not aim to be backwards and forwards compatible over a long-period of time, but we do want to be able to deploy the client and server independently over a reasonable period of time. This is important because it means that the companion and client do not need to be kept in lock-step. In scenarios such as a "Device Lab" in a data center, it's reasonable to have the companion deployed on a schedule that may be different to the clients. Fortunately, gRPC has support for clients and servers talking with different versions of the underlying Protocol Buffers.
We actively welcome your pull requests.
- Fork the repo and create your branch from
master
. - If you've changed the gRPC interface, the Pull Request should contain changes to the client and the server to support this.
- Changes to the the gRPC interface in the companion should be backwards compatible with older clients as far as possible. Any breaking changes will be versioned in minor releases.
- Changes to the CLI that are additive are fine, breaking changes will need to be backwards compatible.
- If you haven't already, complete the Contributor License Agreement ("CLA").
In order to accept your pull request, we need you to submit a CLA. You only need to do this once to work on any of Facebook's open source projects.
We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.
All issues will default to being created with the issue template. Please fill in as much as makes sense.
- 2 spaces for indentation in the Objective-C++ companion and the python client.
- 80 character line length for python. Please run
black
against python code.
By contributing to idb
, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.