BrainBrowser for the People

Preparing Software for Open Source Development

Tarek Sherif

McGill Centre for Integrative Neuroscience

What is BrainBrowser?

• JavaScript library for neurological data visualization
• Began as an application in April 2010
• Refactored into reusable library in 2013
• Open sourced in March 2014

Why Open Source?

• More sustainable long-term
  • Lighter financially
  • Knowledge about the software is shared
• Researchers trust code they can audit
• Learn what people want
  • And have them contribute the changes!
• More eyes on the code

How do you get there?

• Choose the right license
• Make your code accessible
• Let people know about your project

The License

• BSD/MIT
  • Have to give credit, but not much else
• GPL
  • Have contribute changes back if software is re-released
• Affero GPL
  • Have contribute changes back if software is deployed on the Web
• Be aware of compatibility issues
  • Incompatible licenses can prevent software or libraries from being used together
  • Go with a known license

Accessible Code

• Clean code base
• Documentation
• Tests

Cleaning the code base

• Consistent style
  • Code should be readable
  • Create a style guide!
• No unnecessary files
• Directory structure reflects structure of software
• BFG Repo-Cleaner (for Git)

Cleaning the code base

• BrainBrowser then
• BrainBrowser now

Documentation

Help people get up to speed

• API documentation
• Tutorials
• Sample applications

Documentation

Documentation Generators

• Let you comment your code and write docs at the same time
• BrainBrowser Documentation Comments
• Generated API Documentation

Testing

• Provide something that lets contributors know they're not breaking anything
• Automated test are ideal, but there are other options

Testing

Testing in BrainBrowser

• Graphics applications are hard to test automatically
• BrainBrowser has some unit tests
• Most testing is done with example apps that use all functionality

Raising Awareness

No contributors if no one knows about your project!

• Scientific publication
  • If the project is mature enough
• Connecting to developers can start earlier
  • Interested in the technologies being used
  • Many of our projects are unusual uses of their component technologies

Raising Awareness

• Hackathons
• Meetups
• Social media

Hackathons

• Developers get see and use each other's code and software
• Walk people through how to use it
• Find out what the pain points are for users
• Ideally in your field
  • But not necessarily!

Meetups

• Many cities have tech meetups
• People are often interested in novel uses of languages, tools, etc.
• Spread the word and talk to talented developers

Social Media

• Find groups related to field, technologies you use
• Or just write to people or blogs that might be interested
• For BrainBrowser, we found groups related the following topics to be very receptive:
  • Neurology
  • Open Science
  • WebGL, HTML5, JavaScript

Thanks!

tsherif@gmail.com

http://tareksherif.ca

@thsherif