Creating a Python open source project

Martin McBride

2021-06-23

This article is a quick guide on how to create and run your own open-source project. Specifically, it assumes it will be a Python project, although many of the things covered here can be applied to other types of project.

This isn't a guide on how to set up a GitHub account and commit your first source files. Instead, it focusses on the wider whys and hows of open source development, and will hopefully help you to avoid the common pitfalls.

Why do it?

People create open-source software for many different reasons.

Quite often, a developer will decide to create a piece of software for their own use. It is then a secondary decision to make it open-source, because why not? There is the satisfaction of seeing your software being used by other people and the warm, fuzzy feeling of doing some good in the world.

Some people embark on an open software product to learn new things, for example, to use a new language, programming technique or problem domain. Having an open-source product is a great way of learning-by-doing.

Others develop products to raise their profile, perhaps to show off their skills on their CV, or perhaps to help build a following on a blog or social media. A good open-source project will eventually build a community, which in turn helps to improve the project as users submit feature requests, bug reports, or even new code.

And finally, you can monetise an open-source project if it gets big enough, as we will see later. And that doesn't mean selling out - there are some win-win strategies that benefit the project owner and the user community, for example by creating youtube videos

There are also a few downsides. The most obvious one is that you can't sell normally software licences. Less obvious is that, at least in theory, someone else could fork your project and start their own parallel project and take your software off in a different direction. That is actually quite unlikely unless you develop something as big as Linux.

What should you develop?

If you are reading this you probably already have an idea for an open-source project. Or you may have several. It might be best to start with something small to start with.

Generally in Python, you are likely to be developing a library, a framework, a utility, or perhaps a full application. A library is probably the easiest, particularly if it is a pure Python library with no unusual dependencies. One obvious advantage of developing a Python library is that it will be used by other Python programmers, so you can assume they probably know how to install it.

Applications are at the other end of the scale. If it is a desktop application is aimed as a general user, you will probably need to provide a user-friendly installer, and decent user documentation, or you will not appeal to most users. This can be a large undertaking.

My main project at the moment is generativepy, which is a library for creating generative art images and animation.

Hosting

Where should you host your open source project? Github is pretty much a no-brainer. It is free, it works, everybody knows about it. Even Google use it to host their open-source projects!

Aside from the source code itself, things like user documentation can also be hosted on Github, but you shouldn't necessarily do that. Many open-source projects have their own websites. We will look at that later.

Licences

You really need to licence your software. Firstly, if you don't explicitly state that the code is open-source, users won't know whether they are allowed to use it at all. Secondly, it gives you the chance to decide how people are allowed to use your library.

There are quite a few well known open source licences, it is generally best to choose one of those unless you have a good reason not to. There are two broad types:

Permissive licences are licences that largely allow you to do what you like with the software. Examples are the MIT Licence and the BSD Licence.
Protective licences are licenses that have restrictions on how you can use the software. The GPL Licence is one example.

It is entirely up to you. Personally, I prefer to use a permissive licence, because I am happy for my code to be used as widely as possible. I generally use the MIT Licence, it seems to be as good as any. Some people prefer to use GPL because they feel it helps promote open-source software.

Naming your open source project

Every project has to have a name, and you can call it anything you like ... more or less.

You might choose a purely descriptive name, or a clever pun, or something from mythology or culture that relates to the software's functionality in some obscure way, or something else. If your project is a Python library or framework you might decide to include "py" in the name. It is your choice.

But there are a few pitfalls to avoid:

Obviously avoid anything that could impinge on an existing trademark. The last thing you want is to be told later on that you can't use the name, especially as this most likely won't happen until your project starts to get popular.
Avoid names that are already used by other open-source projects. It just creates difficulties and confusion for you, your potential users, and the other project.
Check that the matching domain name is available, as well as any social media accounts you might want. If it is a tiny project, you might not want to do bother with a specific website. But if it is something you are hoping to grow over time, it is not a bad idea.
Check that the name is available on PyPi.org (see later).

If a Google search on your chosen name turns up no matches (and yes that is possible) you are probably good to go. If your name is not completely unique, or even if it is a commonly used word, you might still be OK, but you need to check further that it doesn't relate to any existing products, companies, trademarks, or anything else that might cause legal problems or user confusion.

Releasing

So now you get to develop your project or at least the initial MVP. And test it, of course. When that is done, how do you go about releasing it?

First, you should tag and release the version on Github. This means that users can always easily download Vx.x, even if the main source tree has moved on.

You should also add your release to the Python Package Index (PyPi.org). This is very useful because it means that users can install your software using pip, for example:

pip install mylibrary

To do this you will need to create an account on PyPi.org, and follow the instructions here. It isn't difficult, you just need to create a simple text config file, then run a couple of commands to create a distribution archive and upload it.

This procedure is ideal for libraries, frameworks, and simple utility programs. If you are developing a full application, you will probably need an installer for each supported platform, which we aren't going to cover here.

Documentation and support

If you want people to use your software, you will need to document it. You might also want to provide user support in other ways, such as bug reporting and discussion forums.

The minimal approach, for library code, is to use Python docstrings to document your functions and classes automatically (Sphinx is a good choice for this). These can be hosted on Github pages. As an alternative, you can also place your documentation on readthedocs, which can be set up to automatically generate your documents.

For more complex projects, you might want to provide tutorials and examples. That is where having a project website can be a good idea. It gives you more control of how your information is organised and presented. It also means you get to keep the traffic you generate, rather than sending it all to someone else's website.

Github allows users to submit bugs and issues to your project, and also allows users to submit pull requests that you can choose to merge into your codebase.

Monetisation

The nature of open source is that you don't make money by directly selling your software. Still, there are many ways you can monetise your open source project, perfectly ethically.

When you create an open-source project, you become the leading expert on that project, and your website becomes the primary, trusted source of information. Of course, that is meaningless if nobody uses it. But if you manage to create a project that takes off, it is SEO gold.

The most obvious way to monetise this traffic is via advertising. Even Google ads on your website can bring in money if you get enough traffic. Youtube tutorials can add to that.

Not everything has to be free, and there is nothing to stop you writing a book or training course that people pay for. Of course, anyone else can do the same (and you should be very pleased if they do), but you are the one person who knows the software inside-out.

For bigger projects, there are various business models for monetising open source software:

Offering consultancy or support for commercial users.
Creating paid versions of the software, possibly with extra features that aren't part of the open-source version, or guaranteed maintenance for x number of years, or customisation for a particular use case, etc.
SaaS (for cloud-based systems). Of course, people can just host the system for free on their own cloud, but many might prefer to pay for a hosted system.

Summary

Developing open-source projects is a lot of fun, and you can learn a lot by doing it. At its simplest, can just be a case of creating Github account and cracking in with the coding. But if you have a longer-term project in mind, it is worth putting in a bit of preparation before you start.