Happy new year! Three weeks ago we published a proposal for an API review process on GitHub and asked for your feedback. The process is now in-place and documented in our developer wiki.

Review process

Our primary goal with this review process is to provide a good balance between OSS agility and ensuring high quality APIs. This requires having a centralized body that can continue to review each and every API.

Here is how we approached defining the process:

• Designed for GitHub. In order to be sustainable and not be a hurdle for contributors the API review process must feel natural to folks familiar with GitHub.

• Efficiency. Performing API reviews requires looping in a set of experts. We want to conduct API reviews in an agile fashion without randomizing the reviewers or community members.

• Transparency. We can use the same process for both internal as well as external contributors. This allows contributors to benefit from the results of API reviews even if the implementer isn't external.

GitHub is generally based around the pull-request model. The idea is that contributors perform their changes in their own fork and submit a pull request against our repository.

For trivial code changes, such as typo fixes, we want folks to directly submit a pull request rather than opening an issue. However, for bug fixes or feature work, we want contributors to first start a discussion by creating an issue.

For work that involves adding new APIs we'd like the issue to contain what we call a speclet. The speclet should provide a rough sketch of how the APIs are intended to be used, with sample code that shows typical scenarios. The goal isn't to be complete but rather to illustrate the direction so that readers can judge whether the proposal is sound. Here is a good example.

For more details, take a look at our developer wiki.

Review notes

Today, we've also uploaded a new repository that we'll use to store API review notes publicly. Notes are generally comprised of a text document with high-level notes and a detailed API diff with notes associated with individual APIs.

Yesterday morning, we reviewed some API additions to immutable collections. You find the corresponding notes here. An example of an API diff with associated notes is also available.

What's next?

Next week, we'll plan to perform the first review of the backlog that is filled by the community. We'll record the session and upload a video as well. While we don't necessarily plan to record every meeting, we plan on doing it on a regular cadence so that you can take a look at the sausage factory and understand how these reviews look like.

Summary

Together with the community we've setup an API review process. We've also created a new GitHub repository that will serve as the container for the notes.

Please let us know what you think!