LRUG talk: "Patches Welcome!"

Posted by Denny at 22:00 on Mon, 09 Nov 2020

I gave a talk at LRUG tonight. The title I went with was "Patches Welcome!", although a more prosaic title could have been "Why I do open source software development". It covered how I got started in open source and what I learned from that (professionally and philosophically), as well as what I'm currently working on (ShinyCMS, mostly!) and how I can use my own projects to help other people.

LRUG recorded the talk and have shared the video:

And here are my notes (which I more or less stuck to):

My name is Denny, and I'm an open source software developer.

That's not my day job - for the last few years I've been working at a political campaigning organisation - but as I'm sure you've all noticed, politics has been very dull and uneventful for the last few years, so today I'm going to talk about contributing to open source software projects.

I have a few projects of my own, but the main one - or the main two, depending on how you look at it - is called ShinyCMS. ShinyCMS is an open source content management system - originally written in Perl, starting in 2009 when I was doing freelance web development, and still maintained now. And alongside that, for the last year or so, I've also been rewriting ShinyCMS from scratch in Ruby on Rails.

I'll come back to that in a bit.

Although ShinyCMS eats most of my personal coding time, I do contribute to other people's projects too - usually fixes for small-ish problems that I've run into while using their code myself. Some people like to find opportunities to contribute by looking at a popular project's GitHub issues and picking one that sounds interesting, but personally I find it more motivating to try to fix things that have really annoyed me recently!

(Eric Raymond's term for this, in The Cathedral and the Bazaar, is 'scratching an itch' - which is probably politer than any term I would normally use for "things that have annoyed me recently")

Earlier this year I contributed small patches to a few different Ruby gems, to help cut down the tidal wave of deprecation warnings that appeared in everybody's logs when Ruby 2.7 was released. Now, I can't claim that was entirely altruistic on my part - the warnings were REALLY annoying me - but it was still nice to give something back to the ecosystem of gems around Ruby and Rails, which has been providing me with so many cool building blocks to play with as I make the new version of ShinyCMS. And of course, I could have just hidden the warnings - but my instinct was to fix them instead, and to share those fixes.

And contributing fixes to those gems was an interesting personal milestone for me as a Ruby developer. As the history of ShinyCMS suggests, until a few years ago I'd been coding in Perl for quite some time - over 15 years in fact - and so I'd got pretty comfortable there. In fact I was so comfortable that I had almost forgotten what Imposter Syndrome feels like ;) Changing languages soon fixed that, and I was back to being constantly and painfully aware of how much I _don't_ know. So, it was reassuring to realise earlier this year that I've now reached a point where I can make useful contributions to open source projects in this new language.

The reason I became a Perl developer at the start of my career was ... well, pretty much random chance. It was 1998 and I was at university, a 'mature' student (at the age of 25) about halfway through a degree in Computing. For a uni project, I contacted a lecturer at another, nearby university with a question about one of his research papers. He suggested I go to see him in person for a chat ... and somehow, after a rather longer chat than planned, I walked out with a summer job. Starting in a few week's time, I had agreed to build a prototype of a feature-packed website for him to use in a grant application that autumn.

Between you and me, this was a little ambitious on my part, given my level of web development experience at the time.

Yes, it was zero.

However, I was vaguely aware of an open source Perl CMS that I thought would make a reasonable starting point for the functionality he wanted. So I downloaded that and started trying to modify it and suddenly I was a professional Perl developer - if you're willing to allow a very loose definition of the word 'professional'.

Fortunately for me, pretty early on in that project I stumbled across the Linpeople IRC network - the network which would, several years later, become Freenode. Back in those days though, the #perl channel there was mostly a wretched hive of scum, villainy, and flaming newbies for lols, so I didn't spend much time in there. Instead, I ended up asking my newbie questions in #linpeople itself, where ... people answered them.

It is impossible to overstate how much that IRC channel, or rather, the people in that IRC channel, influenced the course of my career, and hence my life. Dozens of different people, many of them professional software developers who no doubt had 'better' things to do, answered my entry-level questions day after day - on quite a range of topics - with many of them taking the time to 'teach me to fish', rather than just handing over the answers.

Which is good, because although I said a minute ago that I was using an 'open source' CMS, on further investigation that wasn't an entirely accurate description. It _became_ an open source project, called Slash - it was the code that ran on - but back then it had no licence, and it wasn't officially released. It was just a tarball available for download from the personal website of Rob Malda, one of the guys who started Slashdot... with an accompanying note saying that if you emailed him about it, he would block you immediately.

So instead of the community and tools and infrastructure I would now expect to find around any credible open source project, there was just this little group of a dozen or so Perl developers - who had somehow found each other despite this being the pre-historic Before Stack Overflow era - all trying to make Slash work without asking Rob any questions, or in any other way bothering him, in case he got annoyed and withdrew his permission for us to use his code at all.

Instead we shared our own updated versions of that original tarball, taking turns hosting the latest version with all our accumulated fixes and extra docs and whatever else we'd added to the mix. And that was the other half of my introduction to the open source community. On the one side, these knowledgeable and incredibly helpful people on Linpeople, and on the other, this ridiculously determined little mutual support group trying to figure out the Perl code of somebody who (I eventually found out) had taught himself Perl by writing that same CMS. In hindsight, it was possibly not the best code I have ever worked with. ;)

Nevertheless, by the end of that summer I had actually built a pretty decent prototype of a website which could be used to support the existence of a 'Community Learning Network':

Screenshot of Earth Summit for All website

As you feast your eyes on that masterpiece, I will admit that design isn't my strongest skill - I basically just inflicted the project's chosen, slightly '70s colour scheme on the standard, very '90s Slash front end design.

But the resulting website did have news (front page and sub-sections), moderated conversations, and contextual polls, as well as proof of concept for a local currency and facilitated barter system. And Gary (the guy who had hired me) was able to use it to successfully secure funding for the next stage of his project - so that was a happy ending!

At the same time, largely thanks to the residents of #linpeople, I had probably gone through more useful professional development - things still relevant to my career today - in those few summer months than my Computing degree managed to impart in its entire three and a half years.

Now, at the start of that project, I was already a bit of an open source fanboy - which was how this whole thing had got started actually, Gary was fascinated by the Free Software Movement, and it was our conversation about that which turned into the job offer. And it was because I knew the Slash code was available that I said I could do it. I may even have thought it would be relatively easy.

You're allowed to laugh at that.

In hindsight, I can absolutely guarantee that this story would have ended in abject failure to deliver anything useful on my part, and no funding for Gary's research project, without the help I got from all those amazing people in the open source community.

And so now, more than 20 years later, based on that and all my subsequent experiences... well, for a start I am considerably more pessimistic when estimating project timelines :) But also; I am an even bigger open source fanboy now than I was then. But I have experiential evidence on my side now - open source has proven itself to me time and time again, throughout my career, both the software and the community. Or communities really, a tribe for every technology - it's not a single homogenous group.

And despite all the time I've put into a variety of those open source projects and communities over the years - including several years as network staff on Freenode itself - I think I will always feel endebted to the community for that first astonishingly supportive encounter with it, and I will always be looking for new ways to pay that forward.

Which brings us back to ShinyCMS.

A few weeks ago I moved a growing collection of minor TODO items for ShinyCMS out of a text file on my laptop, and into GitHub issues - about a dozen items in total maybe. I tagged some of the new issues - the ones that looked less likely to bite innocent passers-by without provocation - as "good first issue", because it's one of the default tags on GitHub and well, why not. And the next day I woke up to an email from GitHub, letting me know that they had automagically created a page showcasing those issues, to encourage less experienced developers to pick them up.

I have no idea how much visibility that page has, but it set me thinking. I've always admired the way some open source projects go above and beyond to bring in and support new developers, especially people who might not have found their way into coding otherwise - the Dreamwidth project was particularly good at this, back when they launched. For those who don't know it, Dreamwidth is a blogging website based on a fork of the LiveJournal code, and they built a great community around both their site and their code. In particular, they were the first project I was aware of that really put a lot of effort into proactively bringing more women into an open source project, as well as people from non-programming backgrounds, and then they put even more effort into making sure that all those people had a friendly and well-supported first experience of open source development.

Obviously I don't expect to have anywhere near as many opportunities as a project that size does to make that kind of difference to somebody - but I would hate to miss even a single opportunity that does come my way. Or the opportunity to create an opportunity.

Professionally, a few years ago I moved from freelancing and contracting, into a full-time team lead role. Since then I've spent an increasing amount of my time mentoring less experienced developers, which I've found really rewarding - and the connection between that and my quest to 'pay it forward' in open source is pretty obvious really. Once a bot at GitHub points it out by generating a webpage to specifically attract new contributors to my project. Ahem.

So, not to be outdone by the bot, I was wondering what else I could do to encourage and support people who might be considering picking up one of these 'good first issues' as their first contribution to an open source project - and particularly people who maybe were hesitating, not quite confident of their skills and experience. In the end, I added another tag to most of the 'good first issues' which says 'help offered', and I posted a comment on each issue expanding on that - explaining that I'd be really happy to help anybody who's in that 'not quite sure' position get to a position of 'Yeah, I'm gonna try this' instead.

I made a few suggestions of ways I could help - talking through the issue in more detail with them to make sure they feel like they understand it, talking through possible solutions with them and helping them pick one, or even pair-coding on the fix with them if that would make it approachable for them. Or, something else that I didn't think of, that would work better for them. Basically, if it involves me putting some time and effort into helping them take those first steps in open source development, then I'm willing.

Obviously I was immediately inundated with ... okay, nobody has got in touch yet :) But I feel good about the concept, I think it's the right thing to do, a good thing to do. And the offer is out there now, and it will stay out there, and I will remain willing.

As I said in the blurb for this talk, I assume that basically everybody listening to me right now uses open source software pretty much daily - unless they've accidentally joined the wrong Zoom call - but it's always surprised me how few developers take the step from using it, to contributing back to the projects they use. It's such an easy line to casually step over every now and then - you don't have to write the next Wordpress or ActiveRecord to make a useful contribution, and you don't get put on an on-call rota the first time you submit a PR :)

If you've considered tackling an issue on one of your favourite open source projects in the past, but haven't quite taken the plunge, I (obviously) really recommend getting stuck in. The vast majority of people and projects I've encountered in over 20 years of open source development have been extraordinarily helpful and supportive. And that's becoming more of an intentional position these days too, with many projects adding a Code of Conduct and so on.

And going on my experiences so far, I would say that Ruby project maintainers seem to be particularly friendly! I mentioned at the start of this talk that I'd contributed a few fixes to gems earlier this year - here's a screenshot from one of those PRs. As you can see, you can get a lot of love in this community for a two line patch!

Excerpts from a PR showing a two line diff and a reply with multiple hearts from the project author

That said, one of the final points I'd like to make is that even though you're a developer, your contributions to open source projects don't have to be code. If you love making graphics, somebody will be really pleased to have you turn up in their inbox offering to do them a new logo or icons.

One of the best-known and most-admired contributors in the Perl community 10 years go wasn't a developer, but somebody who took great satisfaction in writing up clear, comprehensive user documentation for systems that didn't have any. I don't know how many of you have had to write a full set of user docs for something you've built, but if you have then you will fully appreciate just how pleased people were to find an entire user manual dropped into their laps.

And of course, you don't have to Go Large and write an entire User Manual for your documentation PR to be welcomed with open arms; according to GitHub, nearly 30% of casual open source contributions are simple typo fixes in documentation. Especially first-time contributions.

In fact, I recently discovered a site that lets you look up the first PR you opened on GitHub, and hey, guess what ... :D

Screenshot of my first PR - a simple docs fix :)

So anyway - that's me and my continuing adventures in open source. If anybody has any questions or would like to generally chat about this subject, please do get in touch. :)

And if anybody has suggestions for more ways, or more effective ways, to offer useful mentoring off the back of an open source project - or how to reach out most effectively to the people who might want and benefit from that opportunity - I would particularly love to discuss that.

Tags: LRUG presentation patches welcome open source

« Happy New Year, Happy New Rails, Happy New Ruby! 🎉 Sidekiq Status »



Testing anti-comment-spam measures haven't blocked ALL comments...

Hello world?


Woo, yay, houpla.