On Open Sourcing Libraries

William Durand has written a great post on how to release code under a free/open source license. It isn’t simply a matter of uploading the latest version of your code, it’s a matter of updating the documentation so that others can contribute easily, so that others know the purpose of the project and how to get it running.

The most important section in the post, at least for me, is being standard:

It is important to use the right tools for your library. Look at your community again, and choose the tools people tend to use. In PHP, we use Composer as dependency manager. Don’t waste your time with PEAR or anything else, use Composer. If you write a Node.js library, register it on npm. For Ruby developers, distribute your library as a gem. For C# developers, use NuGet.

Another example, in Symfony2 it is considered good practice to add documentation in Resources/doc. It is a convention. Don’t duplicate your documentation. Add a link to quickly jump to this folder on your README file instead.

He outlines what a README should include:

  • name
  • description
  • Usage section
  • Installation section
  • Contributing section
  • Testing section
  • License section

The project should include a file that clearly states which license is being used and should be clearly visible in the README or any other project home page.

The project should be tested and have some kind of automated tests:

Open Source projects are a way to write beautiful code as there are no deadlines, and no “customers”. Keep in mind that your projects show what you are able to do. As a developer, your library is your business card.

Write tests, a lot! How do you expect people to contribute to your library if you don’t provide a test suite? So, write tests, and use Travis CI. It is all about adding a .travis.yml file describing how to run your tests. It is another way to document how to run the tests.

Add a status image to your README file too.

Take a look at online tools such as Scrutinizer for PHP and JavaScript, or Puppet Linter. Automate as much as you can.

I think I’ll write a HowTo based on Mr Durand’s blog post.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.