Want to Contribute to RAMCloud?

Most of the current RAMCloud code was written by members of the RAMCloud project at Stanford. However, several people outside Stanford have made significant contributions, and we would be delighted for more people to contribute. This page contains a few notes for anyone thinking about writing code that could become part of RAMCloud.

We've tried to implement RAMCloud with a high level of craftsmanship, and we are proud of both the system architecture and the quality of the code we have produced. We want to make sure that this quality is preserved in the future, so we expect a similar level of quality from any new code contributed from outside the project. Here are some of the things that we consider essential:

• Coding Style: All of the RAMCloud code uses a common coding style; there is some information about our style on this Wiki at Coding Conventions and Style Guide, but the ultimate source of truth is the existing code. Compare your code with existing RAMCloud code and make sure that your style conforms in every way: indentation, variable naming (e.g. camelCase, not underline_separators), location of curly braces, etc. You may feel that there are better ways of doing things than the way we have done them, and you may well be right, but please follow our conventions anyway: the most important thing is that the code has a uniform style, and there is no agreement about which style is best.
• Documentation: We have fairly extensive internal documentation for RAMCloud. Every class, every instance variable of every class, and every method must be documented. We use Doxygen format for our documentation. See Documentation Guidelines and Amendments to Current Documentation and Testing Guidelines for additional information about how to write documentation. Please make sure that your documentation is at least as good as the existing documentation and code.
• Unit Tests:  All code must have unit tests with 100% test coverage by lines; the only exceptions are for a few low-level modules where it is difficult or impossible to write meaningful unit tests  (e.g., some NIC drivers). We use Gtest as the framework for our tests. Please follow the style for the existing tests. The most important thing is that tests are isomorphic to the code.  This means that there is one test file for each source code file; within each test file, the tests are grouped by the method they are testing, and the order of the tests reflects the order of the methods within the source file.  The tests for each method are ordered according to the lines of code within the method that they test. This isomorphic approach makes it relatively easy to  tell whether a particular piece of code is properly tested, so we can maintain coverage as the system evolves. We use a white box approach to tests, where we write the tests while looking at the code, to make sure we have tested all of the code.
• Performance: RAMCloud's main claim to fame is its performance. Unfortunately,  performance is very difficult to maintain: most enhancements tend to make the system slower.  When making changes, please think about the potential performance impact, and run tests to make sure you have not damaged performance.  We have two performance test suites that you can run before and after changes to make sure you have not introduced performance problems. The "clusterperf" tests run on a RAMCloud cluster to do system-level tests such as read and write operations. The "perf" tests measure the performance of  low-level system components, such as Buffer manipulation; these tests run on a single isolated machine. We record the results of both of these test suites on this Wiki from time to time (see clusterperf benchmarks and Perf benchmarks], so you can see how your performance compares to the numbers we have measured.
• Open Source License: for us to use your code, it must use the same open source license that we use on the rest of the RAMCloud code. You may change "Stanford University" in the copyright notice to your name, or the name of your organization, but the rest of the notice must be exactly the same as what we are using elsewhere in the code. It's up to you to make sure you have received any appropriate organizational permissions, and that your code does not infringe on any other copyrights or licenses.

Here's how things will work if you would like to contribute enhancements to RAMCloud:

• You code and test your enhancements, making sure to meet the requirements described above. When you're getting started, it's probably a good idea to send an email to the ramcloud-dev mailing list to let us know what you are planning to do; we may be able to give you some initial feedback that will allow you to work more effectively.
• You submit a code review containing your enhancements. The RAMCloud code review site is publicly available on the Web at http://rccodereview.appspot.com/. To submit a set of patches for review, you can invoke scripts/upload.py in your RAMCloud source directory. This will submit a diff containing your uncommitted git changes (to find out how to specify other patch sets, invoke scripts/upload.py with the --help option).
• Send an email to the ramcloud-dev mailing list to let us know about your proposed changes (you must be subscribed to the list for posting privileges).
• Some of us will review your code and most likely make suggestions for improvement. You will revise, and we will repeat this process until we are all happy with the code.
• Then you can send us your patch and we will apply it to the RAMCloud sources.
• Over time, if you make multiple contributions, we will give you direct access to the repository so that you can make commitments yourself. However, we will still expect you to go through code reviews.
• Eventually, once we've seen that you can write high quality code, we may relax the requirement for code reviews on all submissions. However, we still encourage you to get code reviews for major changes; we do this ourselves, and it helps to maintain a high level of quality in the source base.