So you want to open-source some of your code – perhaps share it on GitHub or build a business around it on Binpress – and you wonder how to go about it. In this post I’ll cover all the basics of taking the source of an existing project and preparing it for public consumption.
1. Prepare and normalize files and directories
The files needed for the project you want to publish might be scattered over several folders in your project, with adhoc, almost random structure. Now it’s time to organize them in a coherent, consistent structure, preferably by borrowing from commonly used structures in other open-source projects. An example for such a structure for a Zend Framework project:
/public -- All the publicly accessible files /images /styles /js /library -- Generic reusable server-side code /application -- Application specific server-side code /models /controllers /views /tests -- Unit tests (if applicable)
File names should follow the coding standards for the language you are using. We have a list of coding standards for all the languages we support (and we’ll more if there’s demand), and you can easily any not listed by searching on Google.
2. Minimize external dependencies
Try to remove any external dependencies that are not necessary from in your code. This includes extending your personal convenience classes that you will not be including in the project – a common case when you have a stack built adhoc over time. Change the classes to extend the original framework / library classes, and provide any necessary functionality in the project files.
Try to make sure you are not including files that are not being used by the project just for being in the same directories as other files.
3. Remove copyrighted material
You need to remove and / or replace any copyrighted material included in your works. This includes your own copyrighted images and content (including logo) and any other material that might be copyrighted.
If you are not sure about the copyright status of the materials you are using, please visit the source at which you got it from. If there is no indication of copyright status, you are welcome to send us a message to firstname.lastname@example.org to clear content for use.
4. Comment and document your source-code
If you are not in the habit of documenting code or use a non-standard approach, now is the time to work on it a little. Try to use a standard commenting style – for example, the DocBlock style is considered the de-facto standard for PHP.
Familiarize yourself with the standard commenting style for your language / framework / platform, and try to comment your source-code where relevant (over commenting is not needed) – typically class header files, methods and parameters.
If you find you need to add many inline comments in order to explain what some code is doing, perhaps you need to refactor it a bit to make it more readable.
5. Pick a license
Picking the right license for your project has major implications on who can and will use it in their software. There’s a very nice overview of the various free open-source licenses over at Coding Horror, and we will be writing about that topic in the future as well.
Some considerations to make -
- Should you use a viral license (copyleft) or not? (typically, GPL or not)
- Are you considering dual-licensing? especially if you want the other license to be a commercial license, specific open-source licenses would fit specific use-cases.
- Commercial licenses have their own variables as well. You should check the short overview we have on the various clauses that typically appear in commercial licenses (and specifically in ours).
6. Add working examples
Working examples are very important if you want people to actually use your project. If you have a live site already showcasing the project, you should link directly to that. Make sure though that your examples are not password restricted and accessible to normal visitors.
Other examples might include an app on one of the mobile app-stores, or a video demonstrating functionality or the code in a live application.
7. Versioning, hosted repositories and downloadable packages
If you’re not using a versioning system already, you really should. If you are, you should check out one of the hosted repository services, such as GitHub, Google Code and SourceForge. Those services provide features which are useful for open-source projects, such as issue tracking and a public profile searchable within the service directory. Of course, we provide similar features as well – and we have integration with GitHub specifically (and hopefully with other such services soon).
One last important note is to make sure to prepare your a downloadable version of your project. Most of the repository hosting services allow users to download the trunk directly as an archived package, but you should prepare releases as specific tags within your versioning scheme, so people would always receive a stable release by default (while you keep committing changes and new, untested features to the trunk).
If you are publishing your project on Binpress, such a file is what we would ask for. If you imported a GitHub project, you need to select the tag to be used as the download, or you can upload a .zip file directly (created using a free ZIP archiving program, such as 7zip)
That’s it! open-sourcing your code takes a bit of work, but the rewards are certainly worth it. If you have additional tips for preparing code for open-source publication, let us know in the comments below.Binpress Building an Open-Source Business Open-Source