Contributing to a new project – a bit like starting a new job

I have been using and creating open source software for a long time, I am however of the opinion that I never really have contributed anything of significance. Yes, bug reports, your occasional PR – are all important, but I have never ever contributed to anything where the project was high profile or it was a bigger project or system, with many contributors or an organisation behind it.

Recently I have been picking up from a lot of blog posts and podcasts that in order to evolve as a developer you have to get out of your comfort zone. I took the first step some time ago, when I decided to contribute to MarkdownTOC, a plugin for Sublime Text, where plugins are written in Python and my first contribution was the deletion of a single line. I do not program in Python, but I use Sublime Text and this particular issue, was scratching my own itch.

This was not much, but the positive impact was that the author actually welcomed my contribution and we started an ongoing collaboration. Since then I have contributed a lot more on the documentation side and currently I rank second in the number of lines contributed. Not that this is prestigious to me, but it does demonstrate that contributions even when not actual code are significant and are most appreciated.

At some point I fell over a tweet from EFF (The Electronic Frontier Foundation), indicating that their open source initiatives were looking for volunteers and contributors. After some consideration, I always do a lot of considering when about to leave my comfort zone, I decided to give it a go.

I can only speak for my self, but lets take a step back and reflect on comfort zone and open source and why contributing to open source is a comfort zone issue.

If we look at open source in general. You make something and you put it out there for other people to use or not use and it might be scrutinised or not. Luckily the amount of open source today is overwhelming, so you can actually open source your work and if people do not like it or do not want to use it, they pick another an alternative solution to the itch they need to scratch. This mean the scrutiny and feedback might not be as tough as it could be, I guess some open source authors work in areas where their contributions are being used and viewed by thousands of other people and scrutiny and feedback is different, the Linux kernel is an example.

I decided to have a look at the certbot project.

I do not program in Python, it is however an interpreted language and being a long time Perl programmer and based on my very limited knowledge on Python I did expect the two languages to have some familiarity.

After going over the issues labelled as “good first issue”, I decided on issue #4736. I commented on the issue, since I did not want to start working on an issue where somebody was already assigned or were progressing. I got a positive response and I was ready to get started.

Getting started required reading a lot of documentation on how to actually get started, how to contribute and what tools to use. Most open source projects are more than their source code. The have a lot of infrastructure integration and toolchain customisation, where some projects are “fork, hack, test, push”, you have to install additional tools and configure these.

I started by forking the project and got Sphinx up and running on my laptop.

$ pip install Sphinx
$ cd docs
$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
 Running Sphinx v1.6.2

making output directory...

Exception occurred:

  File "", line 133, in <module>
     import sphinx_rtd_theme
 ImportError: No module named sphinx_rtd_theme
 The full traceback has been saved in /var/folders/4s/v4_4270j5ybb60t4kjwk_f080000gn/T/sphinx-err-AmhKOS.log, if you want to report the issue to the developers.

Please also report this if it was a user error, so that a better error message can be provided next time.
 A bug report can be filed in the tracker at <>. Thanks!
 make: *** [html] Error 1

First problem was an easy fix:

$ pip install sphinx_rtd_theme
$ make html
sphinx-build -b html -d _build/doctrees   . _build/htmlRunning Sphinx v1.6.2

Extension error:

Could not import extension repoze.sphinx.autointerface (exception: No module named repoze.sphinx.autointerface)
 make: *** [html] Error 1

Second problem yet another easy fix:

$ pip install repoze.sphinx.autointerface
$ make html 

Finally reaching a success I was able to get started on filling in the blanks.

I scanned the file structure and compared it to the documentation structure.


So I added the missing documentation files. When re-generating the documentation, the following issues were observed:

certbot/ of certbot.cli.HelpfulArgumentParser.add:7: WARNING: Inline emphasis start-string without end-string.
 certbot/ of certbot.cli.HelpfulArgumentParser.add:8: WARNING: Inline strong start-string without end-string.
 certbot/ of certbot.error_handler.ErrorHandler:6: WARNING: Inline emphasis start-string without end-string.
 certbot/ of certbot.error_handler.ErrorHandler:6: WARNING: Inline strong start-string without end-string.
 certbot/ of certbot.error_handler.ErrorHandler:6: WARNING: Inline emphasis start-string without end-string.
 certbot/ of certbot.error_handler.ErrorHandler:6: WARNING: Inline strong start-string without end-string.
 certbot/ of certbot.error_handler.ErrorHandler.register:1: WARNING: Inline emphasis start-string without end-string.
 certbot/ of certbot.error_handler.ErrorHandler.register:1: WARNING: Inline strong start-string without end-string.

A minor nifty trick helped eliminating the warnings. Finally I was left with warnings from Sphinx indicating some files not being part of the overall document tree structure.

certbot/docs/challenges.rst:: WARNING: document isn't included in any toctree
 certbot/docs/ciphers.rst:: WARNING: document isn't included in any toctree
 certbot/docs/man/certbot.rst:: WARNING: document isn't included in any toctree

After this I sent my first PR for issue #4736 all of these where just technical issues, which could be solved by myself. The overall job is far from done. Next step is getting the documentation up to date, meaning the information used by Sphinx to generate the documentation also has to be aligned with the actual implementation and I have just started on this. This does require more knowledge on certbot and more reading up on Python. My notes on Python details are growing as I cover more and more ground and until now and I have learned about.

– inner classes
– naming conventions
– module use and inheritance
– implicit returns
– the None datatype

I have many questions on the actual certbot implementation, but I will ask these with each assignment/file as I was recommended to make a PR per updated file and my first PR is slowly shaping up.

Starting contributing to a larger project is hard work, it reminds me of starting a new job, as you are exposed to: new systems, new tools, new processes and new colleagues. Much of what you do is similar or you have experience from previously, but at the same time everything is different, so no matter what there is a learning curve.

People on the certbot project are friendly and most helpful, this does mean that the issue with the comfort zone is alleviated. At the same time, if you focus on what you can bring to the project in question, the stuff you come with, even if this is just man hours, you cannot fail.

If however all of your PRs are declined, if all your questions are met with silence or all your inquiries are met with obnoxious responses – instead of feeling discomfort, find another project. There are plenty of other open source projects, which will welcome your efforts. And no matter what happens, you will have learned, you will have evolved – and you comfort zone will have grown. No need to be hindered by the comfort zone feeling, get out, there start small, contribute and evolve.

Contributing to a new project – a bit like starting a new job

Prophecies and The Rise and Fall of Programming Languages

Just having read was must be the annual piece in Dr. Dobbs on the state of programming languages entitled: “The Rise and Fall of Programming Languages”, it was with some concern I observed my local minicpan mirror reports being seriously reduced in size.

From January 9th.

authors/01mailrc.txt.gz … updated
modules/02packages.details.txt.gz … updated
modules/ … updated
authors/id/J/JI/JIMI/Statistics-Reproducibility-0.04.tar.gz … updated
authors/id/J/JI/JIMI/CHECKSUMS … updated
authors/id/J/JI/JIMI/Statistics-TheilSenEstimator-0.04.tar.gz … updated
authors/id/L/LT/LTP/Audio-Play-MPlayer-0.05.tar.gz … updated
authors/id/L/LT/LTP/CHECKSUMS … updated
authors/id/O/OV/OVNTATAR/GitHub-Jobs-0.05.tar.gz … updated
authors/id/O/OV/OVNTATAR/CHECKSUMS … updated
authors/id/S/SE/SEKIA/Algorithm-LibLinear-0.09.tar.gz … updated
authors/id/S/SE/SEKIA/CHECKSUMS … updated
authors/id/T/TH/THALJEF/Pinto-0.097.tar.gz 500 read timeout
authors/id/V/VT/VTI/Attribute-Contract-0.05.tar.gz … updated
authors/id/V/VT/VTI/CHECKSUMS … up to date
authors/id/Y/YT/YTURTLE/Nephia-Setup-Plugin-Assets-Bootstrap-0.04.tar.gz … updated
authors/id/Y/YT/YTURTLE/CHECKSUMS … updated
cleaning /Users/jonasbn/.minicpan/authors/id/J/JI/JIMI/Statistics-Reproducibility-0.03.tar.gz …done
cleaning /Users/jonasbn/.minicpan/authors/id/L/LT/LTP/Audio-Play-MPlayer-0.04.tar.gz …done
cleaning /Users/jonasbn/.minicpan/authors/id/O/OV/OVNTATAR/GitHub-Jobs-0.04.tar.gz …done
cleaning /Users/jonasbn/.minicpan/authors/id/R/RW/RWSTAUNER/Dist-Zilla-Plugin-CPANChangesTests-1.002.tar.gz …done
cleaning /Users/jonasbn/.minicpan/authors/id/R/RW/RWSTAUNER/Dist-Zilla-Plugin-PodLinkTests-1.006.tar.gz …done
cleaning /Users/jonasbn/.minicpan/authors/id/T/TH/THALJEF/Pinto-0.096.tar.gz …done
cleaning /Users/jonasbn/.minicpan/authors/id/Y/YT/YTURTLE/Nephia-Setup-Plugin-Assets-Bootstrap-0.03.tar.gz …done

From January 10th.

authors/01mailrc.txt.gz … updated
modules/02packages.details.txt.gz … updated
modules/ … updated
authors/id/T/TH/THALJEF/Pinto-0.097.tar.gz … updated
authors/id/T/TH/THALJEF/CHECKSUMS … updated

With some horror I thought that the prophecies were coming true? – Perl is dying?

As always Perl is declared dead or dying and in this article Perl is mentioned explicitly. I always take these articles with a grain of salt. I write Perl on a daily basis and I am really busy, so I do not consider Perl dead. The article however did not only list the always problematic TIOBE index, but also Ohloh. I actually considered Ohloh dead (sorry, we should not go around considering things dead), but still it hurt since I love Perl and I worry that Perl dies at little every time this is mentioned, so writing the blog post is probably not a good idea at all – since I might be assisting in fulfilling a prophecy.

Anyway – visiting Ohloh, I found out that all of my CPAN contributions listed there had b0rken links to repositories. I have just migrated a large part of my repositories from a hosted Subversion solution, so I quickly ran through all my projects and updated the repository links.

I know that my small contributions are insignificant, but at least I could flag that my CPAN contributions are out there, they are being somewhat actively maintained, as I wrote I am busy, so open source activities are not always on the top of my TODO for whatever little CPU time I have available.

Then the minicpan reports started coming in, in normal size and when I read Perl Weekly issue #129 and discovered that PAUSE had had issues I felt relieved, fear leads to … yoda yada yada.

Tiobe and Ohloh might be statistics trying to say something about how Perl is doing compared to other languages, but judging by the number of updated modules coming to PAUSE (CPAN) on a daily basis, a lot of active development is actually going on.

I did a swift comparison of some package repositories (numbers from the time of writing).

Perl (CPAN): 28.992 distributions (
Ruby: (rubygems): 68.915 gems (
Python (PyPI): 38.887 packages (
PHP (PEAR): 595 packages (

I cannot conclude anything from these numbers, since they say more about the communities and the concept of code distribution and packaging. A statistic from github would perhaps be more interesting. Gabor Szabo wrote a blog post mentioning another blog post on the topic. Here PHP is actually doing quite well compared to Perl.

So taking a step back and looking at the statistics on all the languages I am thrilled to see the sheer number of different programming languages represented on Github (20). That is awesome. I love Perl and I love programming, so seeing how many open source projects and languages are available makes me happy. And it seems that no matter what the statistics say there is still and always room for Perl as a language.

So a note to self is “do not believe in statistics and prophecies”, even though my name is Jonas

But if you however want to play the statistics game on the Perl team, you could do the following:

– join the Questhub quest of releasing a new Perl distribution every month
– put your Perl projects on Github
– mention your projects on Ohloh

Have a nice and productive day programming in whatever language that solves your problem the best.

jonasbn, Copenhagen

Prophecies and The Rise and Fall of Programming Languages