How to bring your code in open-source

Open source is a vast topic decribed in-depth by many online/offline resources. On the practical side, this page entails a few basic steps to bring your code in open source when there is an interest to do so. OpenPATh can provide support should there be any concerns. Do not hesitate to contact us.

This is the first question one has to ask. There are various reasons to be part of the open-source movement as it presents a wide array of benefits. Read extensively about it in this excellent book. For now consider the following few:

Improve the quality of your project by opening it up. Code always contains bugs: this is a fact of life. In order to reduce the number of bugs in the code, you need to increase the number of eyeballs looking at the code and testing the software. Bugs do not like to be observed: the more scrutiny, the higher the code quality. The higher the code quality, the happier the users. Open sourcing the code means that anyone in the world can look at the code, can find bugs, can report them or, even better, can correct them and provide the patch back to the community. This means that open source code has usually a higher quality and is more reliable than proprietary code. Here's some numbers.

Read more about standards and quality.

People will recognize value and they will make that clear by using your software. Some will provide new requirements, propose features or develop parts of it themselves. Inherently, that will build up reputation for your project which, by consequence, will attract more people and validation. Open-source software offers to developers other sources of gratification than just financial. This reference gives an interesting list of motivations.

Open-source is a great way to learn or share new knowledge and skills, to get noticed which can lead to community recognition and unexpected employment or spin-off opportunities. Ghosh et al. surveyed over 2,700 developers about the principal reasons they joined the open source software (OSS) community. Almost 80% of respondents said it was to learn new knowledge and skills, and 50% mentioned sharing knowledge and skills – two intrinsic motivations. At the same time, over 50% mentioned earning money, either directly (getting paid for working on OSS) or indirectly (improving job opportunities) and getting help developing a new software product – two extrinsic motivations.

Read more about open-source motivations.

Open source software yields a lower total cost of ownership when compared to closed source and proprietary alternatives as stated in this article. Having more people working on your project means better code quality. That translates into lower maintenance expenditure and more resource available, leading to additional features developed for the same cost and time spent. Instead of doing all the effort yourself, allow those interested to help you out. There will be some effort in running an open-source project (documentation, community, promotion, issue mitigation, code review, etc.) but it's overall significantly lower than having to do it all on your own. Your project will organically grow to your users needs. This means lower risks of developing a code that has no real value in your line of business.

Read more about open-source cost.

Wouldn't it be great if the scientific proton therapy community would benefit from existing software tools to build up their research on rather than rewriting similar code over and over again? Imagine how fast research could advance if, instead of writing globally duplicate code, people would focus on their scientific research questions. It perhaps suffices to think about situations where you may have needed a certain software tool to carry on your research but you couldn't use it due to proprietary reasons. Picture now having access to roughly most of the tools you'd need via open-source. Isn't that great? In exchange one might think that others would use some of his own software in the same way, if it were open-source. This type of collaboration can be a motivator.

In case you wonder about the relationship between intellectual property and open-source licensing, the following link provides specific information for the Apache 2.0 license.

Read more about open source and accessibility here.

The right license will contain your work in the public domain. It will provide the specific legal protection and general guidelines in how others will be using your code. In brief, it defines the conditions under which the software can be used, modified and shared. Read a fuller story here. Most of the open-source projects referenced in OpenPATh make use of the Apache 2.0 license. Read about it here and here.

To be coherent and avoid intellectual property issues, it is advised to talk to your institution's legal department before choosing a license and releasing your project in open-source.

Navigate more about choosing a license here.

Basic documentation on how to use your code and describing what has been developed is important for people to be able to navigate your project. The documentation does not need to be exhaustive but, at the moment of release in open-source, it needs to cover the main aspects about usability, architecture and critical functions of your program. Many other functions can be documented at a later stage as the project unfolds.

With a functional minimum in place to help understand your code, other people might contribute documentation to the project to clarify something they've been struggling with or a new developed feature. Encouraged and guided, documentation will improve and grow. A set of rules about how to write it can prove helpful to keep it coeherent and, as much as possible, uniform.

For the user manual, brief use-cases with visual content is a good way to go about. For developer API, details on the basic architecture, features, important functions input/output and arguments would represent a solid start.

Read more about documentation importance and good practice here.

Keep track of the evolution of your project by using a revision tool. This is essential in any project and your open-source software makes no exception. It will not only hold a record of code versions, all accessible at any time, but it will also provide backup and enable remote collaboration. Judged by many, the best out there is Git. Alternatively, other tools are available, SVN being an example.

Read more about revision tools here.

A project management platform is a critical tool in the open-source world. Together with the choice of license this controls and contains your code in the public domain. The selection of this tool has to be in harmony with the revision system, described in the previous section, as it essentially represents an organic layer on top of it that will allow you to:

• Provide online access to your project
• Access wikis
• Set milestones
• Manage users and groups
• Manage access and permissions
• Follow activity on the repository
• Collect and resolve issues: bugs, comments, change requests, questions, etc.
• Handle pull/merge requests
• Topic discussions
• Continuous integration and automation

Platforms such as Gitlab or Github are naturally integrated with the Git system and they are highly advisable. A good example of a platform employed for a project promoted in OpenPATh is the Gitlab of OpenREGGUI. Read more about how to make a contribution to OpenREGGUI, as a general showcase. To collaborate harmoniously the pull/merge request mechanism is essential.

Read more about source control management.

Having a project website is important for the visibility and the overall success of your open-source effort. It is not the absolute condition however. One of the most notorious examples of a website for an open-source project is ubuntu. Looking closer, within the projects gathererd by OpenPATh, the website of OpenREGGUI serves a pretty good showcase as well. A website is the business card of your venture. A good business card states clearly and briefly the features of the project, provides access to the software and defines interaction points with the others. The complexity level can vary with the size and demands for each specific case, therefore balance well the needs you may have. No point in overdoing things.

Many small open-source projects don't have a website per se, and they use the source code management system (Gitlab, Github, etc.) to present online the code. The main page and wiki pages can serve very well this purpose, as in the example here.

Alternatively, both Gitlab and Github offer functionalities to build static webpages hosted on the same Git reposository. See Gitlab pages or Github pages.

A template example of a static website generated with Gilab Pages can be seen here.