Published in 09:22 of 07/06/2015 by Bruno Rocha
Bruno Rocha There is more to life than increasing its speed!

Published in 09:22 of 07/06/2015

←Home

10 rules of open source projects

1. Something incomplete is better than nothing at all

If you have a piece of code and you think it is useful. Share it to the community, if this is a code snippet you can share in the form of a gist on github. 

Even if this is an incomplete peace of software put it on github. Maybe missing documentation, tests and code cleanup but share it anyway! 

If this is only an idea, put it in aREADME file or post in to a blog.

2. Explicit is better than implicit (be honest)

Always include advices and notes in your project README or in code comments. If the code is incomplete and you are not sure if this is safe, please make it explicit to the community.

You can simply put CAUTION note: 

"Use at your own risk" or "Untested alpha version do not use in prodution" notes on the project page.

3. Release it carefully

Following the same principle as the item #2. If you think your software is good and has a good value to others. Or if you are wondering some kind of profit from it, do careful releases. what it means?

  • Use versioning, tags, semantic versioning
  • Only upload to the Package Distribution Central if you are sure the code is ready for production!

In Python world everyone uses pip install to get packages from PyPI. When something is installed throught pip you consider it is ready for production, there is no sense on using a not ready software installed from package distribution, beta testers will use source code and sometimes people who installs software from pip will trust on it without reading the docs (please read the docs).

The main problem is that broken packages on pip will be bad for Python itself!

Specially beginners will think that this is part of official Python platform. be careful!

4. Follow the patterns

Even if you do not like your community patterns. Remember you are not alone and since your project is open sourced it belongs to the community! 

In python there is a set of good practices and PEP-8 rules. You can break some special cases (as you can read in The Zen of Python) but you need to be clear on the justification. It will be better to help and broader adoption if you follow the patterns.

5. Write tests

Maybe you do not like to follow TDD. No problem! you can write tests after development, maybe you do not care of having 100% of coverage, no problem! But please!! 

Write some tests. 

Only you know which tests are the most important ones. Your project  community will not know what to test if you do not give some hints. 

Testing is the better way to begin contributing to a software. So write at least one test or your project doesn't get confidence.

6. Do not keep waiting for community help, your project depends only on you!

Sometimes you start a great software. Release it to github. Advertise it on blog posts and social networks. Talk about it on events. And even doing all that stuff your project doesn't get attraction and you demotivate. 

If you think your project is good keep on rocking it! 

Do not expect community help. The project depends only on you, and help and adoption will come naturally as it grows and shows its value. It can take some long time to get it.

7. Write the F** Docs!

You do not have to use some difficult documentation platform. Neither write in specific weird markup language (a.k.a RST). You can use any writing platform you want (but please don't use a ms-word document). 

Even more the community is adopting markdown as default and prefered for documentation. Markdown is easy and there is a lot of nice tools as MkDocs and good editors. 

You can just create a docs folder and fill it with a bunch of .md files, or you can use the built-in github wiki! Even if incomplete, write some docs, not everyone likes to use source code as reference.

8. Write an awesome documentation!

I know it is repeated, but this is important! Maybe more important than the software itself. Because without good docs your software will not be used and you will not get help!

Follow good examples. Even if your documentation is only a single README file you can do an fucking awesome README file!

9. Tutorials, videos, blog posts

Well. Documentation rises again. But now in form of content drops.

You have to show users and developers how your software works and what is the value on it. You can give tips on twitter. Record screen-casts, blog posts, a nice tutorial and advertise show cases. 

Just do it!

10. Community matters

Build a community! It can be done with simple and small actions.

  • Invite your friends to code in a sprint.
  • Give talks on events.
  • Create a nice logo and maybe a cute and funny mascot to print in stickers and stamps and give it to your friends.
  • Help other projects. You can help to fix some bug in a library you are using. And then advertise that you are using that library in your own project. 

So you will start building connections (it can grows to a whole ecosystem).

Let anyone helps! 

Maybe your priority is to fix difficult issues. But beginners will always try to find the easy to solve. So create some simple issues. Sometimes adjusting a .css file or fixing formatting in documentation. Or get your code PEP-8 compliant. Putting badges on your github page. All things that you can let the community to do. It will help your project to gain some angagement. Focus on difficult tasks and create issues for the easy ones, it is a good entry point for contributors!

If you are looking for a great project to contribute give Quokka CMS a try! :)

  • Publish your Python packages easily using flit in python · 20:19 of 08/22/2017
  • The quality of the python ecosystem in Slides · 21:23 of 06/27/2017
  • Consumindo e Publicando web APIs - PyData São Paulo - 2017 in Slides · 00:58 of 03/29/2017

  • comments powered by Disqus Go Top