Open Source

How to Release Your Code as Open Source

Basically, it boils down to just a few steps. But as usual there are a lot of unstated assumptions and other details. These are briefly mentioned in the following step-by-step instructions. This section is under construction, it is going to include more details and pointers to in-depth documentation. The TLDP has a very good and extremely detailed how-to that is required reading for anyone who plans to release open source code on a somewhat regular basis.

1. Make sure that you actually own the Copyright to the code.
   • Fortunately for academic work in Sweden, this is rarely in doubt. For example, work of Masters' and PhD students belongs to the students, thanks to very sensible laws.
2. Organize your files into a good project directory hierarchy.
   • Choose a useful top-level directory name (reflecting the project name, with version numbers as appropriate).
   • Choose good file names that adhere to some (self-apparent) naming convention.
   • If you have lots of files, structure everything into sub-directories (e.g. by sub-project, or by type of file, or whatever categorization makes sense for the project).
3. Ensure that the sources are sane.
   • Follow sensible naming conventions and coding style. For an example with nitty-gritty details, have a look at the Google Style Guide for inspiration.
   • Make sure that everything builds form scratch and runs as expected.
   • There must be a minimum of documentation bundled with the source, such as brief descriptions of the main functions.
4. Choose a license that is approved by the Open Source Initiative.
   • A very good default choice is the 3-clause BSD license, use that if you're unsure.
   • Other popular choices that are appropriate for academic work include the GPL (version 3) and the MIT licenses.
5. Place a Copyright and license notice conspicuously in each file (ie. at the very beginning).
   • The licenses listed on the Open Source Initiative website are templates where you fill in the appropriate placeholders.
6. Add a README file to the top-level project directory.
   • The README file should state the name and purpose of the project, the Copyright and license terms, some pointers to e.g. project and lab websites, and at the very least some minimal description of the dependencies and the build or installation process (if applicable).
   • It is also customary to place a file called COPYING or LICENSE which contains the actual text of the license. This is especially important for licenses that have a lot of text, such as GPL (as opposed to BSD or MIT licenses, which are very short and easily fit within the header of each source file).
7. Create a tarball and/or ZIP archive of the directory.
   • The tarball should be named after the top-level directory
   • Make sure that the archive extracts into a standalone directory that has the correct name.
   • Make sure that generated or other spurious files (such as editor backups or revision control files) are not included in the archive.
   • Make sure that the build works from a freshly unpacked archive to detect if any files are missing.
8. Place the tarball on an appropriate website.
   • A very good place to put a tarball is of course a website dedicated to the project.
   • The information to put on the website is essentially the same as what goes into the README file.
   • But of course a project website has a much higher potential for growth and impact. For example, see the plethora of project websites hosted on Sourceforge, GitHub, Bitbucket, Google Code, or any other of the numerous free open-source hosting platforms.

Please direct questions and comments to Roland or Slawomir.

The Beginning of Open Source Advocacy at the IS-Lab

Slides of the seminar given by Roland on May 22, 2012