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/htmlRunning Sphinx v1.6.2making output directory...Exception occurred: File "[conf.py](http://conf.py/)", line 133, in \<module\> import sphinx\_rtd\_themeImportError: No module named sphinx\_rtd\_themeThe 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 \<[https://github.com/sphinx-doc/sphinx/issues](https://github.com/sphinx-doc/sphinx/issues)\>. 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.2Extension 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.
cert\_manager.py cli.py eff.py error\_handler.py hooks.py lock.py log.py main.py notify.py ocsp.py renewal.py plugins/ common\_test.py disco\_test.py dns\_common\_lexicon\_test.py dns\_common\_test.py dns\_test\_common.py dns\_test\_common\_lexicon.py manual\_test.py null.py null\_test.py selection.py selection\_test.py standalone\_test.py util\_test.py webroot\_test.py
So I added the missing documentation files. When re-generating the documentation, the following issues were observed:
certbot/cli.py:docstring of certbot.cli.HelpfulArgumentParser.add:7: WARNING: Inline emphasis start-string without end-string. certbot/cli.py:docstring of certbot.cli.HelpfulArgumentParser.add:8: WARNING: Inline strong start-string without end-string. certbot/error\_handler.py:docstring of certbot.error\_handler.ErrorHandler:6: WARNING: Inline emphasis start-string without end-string. certbot/error\_handler.py:docstring of certbot.error\_handler.ErrorHandler:6: WARNING: Inline strong start-string without end-string. certbot/error\_handler.py:docstring of certbot.error\_handler.ErrorHandler:6: WARNING: Inline emphasis start-string without end-string. certbot/error\_handler.py:docstring of certbot.error\_handler.ErrorHandler:6: WARNING: Inline strong start-string without end-string. certbot/error\_handler.py:docstring of certbot.error\_handler.ErrorHandler.register:1: WARNING: Inline emphasis start-string without end-string. certbot/error\_handler.py:docstring 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.
Re-posting of an older post from my blog
Oldest comments (0)