Contributing to the OpenSim Source Code

Overview

The OpenSim project encourages contributions from all researchers. Contributions can come in the form of new models or user-developed plug-ins and other utilities.

We also provide a distribution of the OpenSim source code via a zip file (starting with 3.0) and access to the OpenSim project repository on GitHub. This allows you to see the details of the algorithms underlying OpenSim and, if you build the source code, you can more easily debug the code you use to extend OpenSim. Please note that building from the source is challenging and, as a non-commercial entity, we have limited resources to provide support for the build process. This is an additional reason we encourage the use of the API and plug-ins. 

In reviewing the OpenSim source code, if you discover what you think is an error in the code or an unexpected result, let us know by contacting the project team at opensim@stanford.edu or filing an issue report on GitHub or a bug report on Simtk.org.

At the next level, advanced developers can create a pull request on GitHub to add a new feature, fix a bug, or make other improvements to the code. If you have a well-documented and well-tested plug-in or other utility, we would love to make it part of the main OpenSim distribution so that all users have easy access to it. More details about how to make a contribution to the OpenSim code, via pull request on GitHub, are described below.

The above details apply to the OpenSim API. The OpenSim GUI will be moving to GitHub in the coming months, as well. We'll provide more details about GUI contributions then.

OpenSim Source Contribution Policy

The purpose of our contribution policy is to ensure that OpenSim source code that is merged into the master branch has undergone real scrutiny, thereby reducing the likelihood of errors. Even the best programmers can fall victim to lack of oversight that leads to duplication, inefficiency and, worst of all, confusion. For it to be effective, no one is exempt.

The policy is graduated based on the type of change or addition:

1. All tests must pass before code is checked in (at least in release), with the exception of Case 6 below. An email has to be sent to the team commits list with an explanation for checking something in that breaks a test. At least 3 others must agree that the failure(s) are temporarily acceptable and agree to a plan to address. The change cannot be checked in if any team member opposes.
2. Adding a new class or object/algorithm refactor requires that the author and two other team members perform a code review. The change cannot be checked in if any team member opposes. Approval should be noted with your check-in comment.
3. Adding accessors or other convenience methods requires one other developer to verify and approve (naming makes sense, similar methods do not already exist, etc.) before check-in. Approval should be noted with your check-in comment.
4. Compiler compatibility updates (e.g. for gcc on Mac or Linux) can also be checked once you have confirmed yourself or with at least one other team member that the the build for Windows isn't broken.
5. Bug fixes (that do not also fall into 1 or 2)  can be committed without review BUT the bug fix description and associated bug number (if it has one) needs to appear in your check-in comment.
6. Updates or typo corrections in Doxygen and other comments may be checked in without ensuring tests pass BUT this needs to be noted in your check-in comment.