A couple of weeks back, I saw a request on Twitter for information about how to go about starting or contributing to open source software and projects, and I wanted to share what my experience with OSS has been, and my recommendations for anyone looking to get more involved with it (especially focusing on virtual reality).

Firstly, some background on my experience with open source: I started developing virtual reality applications and prototypes using the Unity game engine. I considered them open source in that all of the source code was available on Github, I freely shared how I built things and information about what I covered, and accepted occasional pull requests when people who forked the project made a small fix or updated something. I also had several “open source documentation” projects, which were technical in nature but were based on tutorials and resources, rather than code, similar to a wiki. In January of this year, I joined High Fidelity, which creates an open source social VR platform by the same name, and got to learn a lot more about larger open source projects — and I got over my fear of contributing to them.

Open source means different things to different people, but generally, it’s used to describe software that makes its codebase available to be read, extended, or modified by contributors. A contributor is someone who adds value to the project through writing new code, fixing bugs, filing issues, writing documentation, and helping maintain the project and people who work on it. Often times, open source projects are sponsored or originate with a single person or company (referred to sometimes as maintainers / core contributors) .

Contributing to, or starting your own, open source projects for the first time can feel intimidating – working in a new project or area of a codebase that someone else wrote isn’t something that we all get exposure to regularly, especially if you’ve spent time working independently on projects for a while. Different projects will operate in their own specific ways (e.g. not all will use GitHub to track issues; some may have restrictions on what types of fixes or features come into the main code base) but a rough outline for the steps to contributing to an OSS project are listed below.

The basic steps to contributing

1. Get your own copy of the source code. If the project is hosted on GitHub, this generally means clicking the ‘Fork’ button, which creates a copy of the entire project to your own account that you can work from. If you need a primer on git, I recommend the interactive tutorial available from GitHub.
2. Create a branch of the project from the master branch in your fork. This is the name that you’ll give the copy of your code with a specific set of changes that you’re going to make. The master branch is generally the ‘base truth’ of the code that makes up an application, so you’ll usually want to work from that branch, especially if you’re just starting out.
3. Make your code changes! Maybe you found a spelling error and you’ve just made a couple of characters different. That’s a totally valid change, and string fixes also get downgraded in projects as lower-priority fixes. Commit your changes to your branch and push it up to your remote copy on GitHub.
4. Ensure that you are following any contributing or code styling guidelines before you submit a pull request. Many projects have configuration files that will define this, or will run a style-check automatically. A pull request is a way to show that you want your changes to be considered in the code base. Usually, you have a conversation about your code and may be asked to make changes by the core maintainers of the repository.

I recommend picking a project that you work with on a regular basis, whether it’s a framework you use in your applications or a plugin that you use in your games. Understanding how the components work together and having a solid concept of what the goals are for the project you want to contribute to are important to being able to collaborate with the core team. Being a passionate user means that you’re already a member of the community – you can think of contributing formally as a way of adding to something you use and like to make it even better!

Some of the things that I recommend new contributors to an OSS project look for:

• Tags for beginner-friendly issues. Not all projects use tags or do their issue tracking on GitHub, but if they do, these can be a good way to filter for tasks that should be easy for someone newer to the codebase to pick up.
• Missing documentation. Find out if an open source project you use needs documentation help. I can almost promise you they do – keeping docs up to date is one of the recurring challenges that I see in development teams. Realize that a documented API has changed? Or that a new feature could use a tutorial to go with it? Take a look at how the team documents these things and consider contributing there in addition to the main codebase.
• Issue tracking. If the project tracks issues on GitHub (or another publicly open tool for bugs and features) you have a couple of options how you can contribute to bugs. First, if you find any – submit them! Before you submit an issue, keep the following in mind:
  • Search the issue tracker and make sure it hasn’t already been submitted
  • Write very clear messages about what you expected to see, what actually happened, and what you were doing. Any additional information about your system can also be useful.
  • Provide a log file when possible — it can help identify issues that the developers could look through.
  • Add a screenshot if there is a visual component
  • Follow up with the discussion and resolution of the issue — it may be an area where you could get some guidance and fix yourself!
• Feedback / Discussion: Often, maintainers of an OSS project will provide a forum for users to weigh in on future feature discussions and project structure. Read through them and participate! If you’re looking to get involved but aren’t ready to take the plunge into a fix yet, this is a good way to learn about the team and figure out the community culture of a project.

Open source is a community — these projects often bring together contributors from all over with a range of different experiences and uses for a project. As with any group of people, sometimes the community can be unhealthy, so never feel pressured into contributing to a project because it’s trendy or cool if you don’t enjoy the way that you’re interacting with the other people who work on the project. Large projects have been known to be completely separated due to unresolved tension between conflicting groups of maintainers, so be vigilant on the way that people on a project interact with each other and whether it’s a group you want to contribute to. Your skills and time are valuable — make sure you find projects that reflect your values. Familiarize yourself with licenses that source code may be released under, and recognize that your contributions will be guided by that. 

Open Source for AR & VR

There are a number of open source projects related to virtual and augmented reality, some of which I’ve listed below. 

VRTK– A great open source toolkit for Unity, VRTK helps reduce overhead for VR development using the Unity game engine. Created by @The_StoneFox, the VRTK project is a beginner-friendly repo that clearly outlines coding standards, a code of conduct, and issues that are open. The project also has a number of places where developers using the toolkit can share their ideas, including a Slack channel.

Aframe – Mozilla’s markup language that wraps around the WebVR API, Aframe is an open source project that aims to make developing VR-enabled websites easier. You can contribute to Aframe directly on GitHub, or to additional components of the Aframe framework (such as networked-aframe) JavaScript, CSS, HTML

Mixed Reality Toolkit – The Mixed Reality Toolkit is a project from Microsoft for developing HoloLens applications and applications for the Mixed Reality VR partner headsets. There is a Visual Studio based project as well as a project specifically for Unity development. C++, C, HTML, Objective-C, C#

OSVR – an open-source schematic for VR HMDs and libraries for cross-platform VR development with guidance from companies like Intel, Sensics, Razer, and Leap Motion. Languages vary

ReactVR – ReactVR is a framework from Oculus / Facebook for developing WebVR sites that utilize their React libraries. Primarily JavaScript based, this is a good project to look at if you’ve already had some experience working with React for traditional apps. JavaScript

LearnVR – LearnVR is a project that I started a few years back to keep track of resources that I found helpful for learning more about virtual and augmented reality. It’s woefully out of date and could absolutely use some love (and it’s a non-coding open source documentation project!) so if you have resources or thoughts of things to add, I would love to hear what you find helpful.