I toggled public, now what?

Some thoughts on open sourcing a contract project, and what does open sourcing a project demands from us as developers

A few weeks ago I had a small open source experience that made me think about how we open source projects, and what should we expect from them.

It all started when Benny shared a link in our community slack group. “This is the project I’ve been working on for the past few months” the message exclaimed. “Take a test drive” with a link. The site (a frontend client for a genealogical site) was really great, clever UI/UX and good execution, I even found my own family tree there!. But when I opened the developer console I was saddened. Non minified, Non revved Js and Css, console.log errors and more problems. I knew the syndromes from plenty of other projects: there was no build process here (unfortunately, quite a common pattern in frontend land). After some correspondence with Benny, he notified me that he had convinced the manager to open source the project and asked me to help out with the build. And so I did, a quick PR with a grunt driven build process took care of that.

1–0 for open source! Or is it?

A few weeks later we met in Israel’s first Pycon, a great open source celebration, and discussed the genealogical project. The context made me think about open source and open sourcing software projects (as opposed to libs); and mostly, what we need to do so open sourcing a project isn’t just a public relation stunt or a way to share the code with a friend who can help, but didn’t sign the NDA. What do we need to have a community around it and make it a genuine contribution to open source, open source developers and free software communities.

As I have already mentioned, this is a Project, not a library that can be used in other projects, or a tool. It can’t be used “as is” in other developer’s projects. So how can it benefit the open source world or maybe: how can it benefit a developer?

Open source projects as a teaching platform

The first thing that comes to mind as a possible benefit for open sourcing this kind of project is for learning. A developer, perhaps wrestling with a similar problem, can go through the code, and see how they implemented family trees using a d3 wrapper. Another developer, just moving to the Angular.js world can use it to learn idiomatic Angular.js using clean module separation, or a “Modern” (2012 modern :( ) front end build process.

The current project is just a “front end client” for a specific use case, so it doesn’t help us much as a “teaching platform”.

The first thing we can fix to make it more suitable for that: Good commenting, relevant generated docs, and explicit readme files can go a long way to help (That goes for libraries and tools writers also.. ).

But this isn’t enough. No one would find this project **ever** between millions of Js code repos, or think of using it as a teaching platform. What good does an open source project do in the forest if no one knows about it to learn from?

Besides having Readme files that include relevant text for search engines, I believe one or two blog posts (which can easily be placed in a project’s gh-pages) describing design and implementation dilemmas and decisions, could go a long way forward to promoting this project as an open source learning space. Is this too much to ask from a Project developer? For a big scale project, I don’t think so.

Contributions

A key part of modern open source culture is contributing code. But code contributions don’t come without a price. Contributions might break the code or change coding style, they may be low quality (for me — every contribution without a test is). They might be not the contributions you were looking for. Sorting this out can take time and effort, which might not be worth it (and don’t get me started on abusive language from wannabe “contributors”).

The first thing is actually telling the open source world what you need. Open sourcing a project without an issue tracker and some actual issues, isn’t very helpful. How can a newcomer who stumbled over the project find what needs to be done? A “normal” open source library might use the issue tracker as a place for users to report bugs, but this kind of open sourced project doesn’t have “open source users” to report bugs and open issues; the developer must do that, at least initially. Time to call Benny, “Hey Benny, where are the issues?”

I dare say that a decent Open Source project **must** have clear contribution instructions (Github makes it easy with auto displaying the Contributing.md file), expected linter/code style checker configuration (for example a eslint/pylint configuration file) that the contributer can run. Also,first and foremost, automatic tests running in a CI environment (and almost all CI providers have an open source **free** offering). Last but not least an AUTHORS file is quite standard: Mention those who contributed time and effort to make this project better.

All of this also works the other way around. If you don’t have this in your project then you can count me out as a contributor.

Taking it further

But what I would really expect from Benny (or other developers open sourcing a middle/big contracted project) and would contribute to open source development communities; would be moving forward from the teaching platform and use the project as a midwife, delivering new libraries into the world. A lot of software development is about finding the right abstraction. If we can find an existing lib that does that for us, it can be very beneficial. jQuery, for example, took the Js world by storm in 2006, since it brought new apis with just the right abstraction over the then existing DOM apis. The abstraction was so good, lots of it later became web standards. D3 did the same for data driven documents in the web, with better abstraction over low level svg and DOM apis. When developing software, “We are standing on the shoulders of giants”, and using proven solutions from open source libs is a great way to do that.

Benny and his team developed an abstraction over D3 for the representation of genealogical trees and the connection between them. This code can be very tedious and hard to reason about, having an abstraction that takes care of that is priceless! Open sourcing a project is good. But separating this abstraction into a stand alone lib (used and consumed in the original project) would be much better! This would allow this code to be easily incorporated into other projects, perhaps in different domains. It would also allow developers to contribute directly into improving this lib, when not covered with layers of technical glue and business logic. This goes for libs also. Separating stand alone modules can do a lot for reusability and clarity. jQuery separated Sizzle css selector engine out of jQuery to be used in other projects. Angular.js was built from the start with different modules not part of core angular.

Hey, this would probably also make the original project code better, less LOC!, more clarity!; with concentration on the problem we are trying to solve! Looks like a win-win.

Or is it?

I know the chances that would happen are quite low. The code is probably intertwined all over the project, incentives aren’t very high, budget is lacking and free time is always in shortage. This is actually the reason I started writing this post: if when the project started, open sourcing it, or parts of it, had been an objective, then code would have been written with the modularity needed for this kind of separation. All stakeholders must value this objective and appreciate the possible benefits and inevitable price. I suspect this part won’t be easy.

I know the “open sourcing” bar in this post is quite high. But moving open source forward needs commitment and effort, toggling the “public” radio button in Github just isn’t enough. So let’s see the “public” toggling as a start of a journey, not the endpoint, of “open sourcing”.