GET/SET methods for open source projects

I’m aware that many of the folks who read my blog already know lots about open source, but I’m also aware that there are many who know little if anything about it. I’m a big, big proponent or open source software (and beyond, such as open hardware), and there are lots of great resources you can find to learn more about it: a very good starting point is Opensource.com. It’s run by a bunch of brilliant people for the broader community by my current employer, Red Hat (I should add a disclaimer that I’m not only employed by Red Hat, but also a “Correspondent” at Opensource.com – a kind of frequent contributor/Elder Thing), and has articles on pretty much every aspect of open source that you can imagine.

I was thinking about APIs today (they’re in the news this week after a US Supreme Court Judgment on an argument between Google and Oracle), and it occurred to me that if I were interested in understanding how to interacting with open source at the project level, but didn’t know much about it, then a quick guide might be useful. The same goes if I were involved in an open source project (such as Enarx) which was interested in attracting contributors (particularly techie contributors) who aren’t already knowledgeable about open source. Given that most programmers will understand what GET and SET methods do (one reads data, the other writes data), I thought this might be useful way to consider engagement[1]. I’ll start with GET, as that’s how you’re likely to be starting off, as well – finding out more about the project – and then move to SET. This is far from an exhaustive list, but I hope that I’ve hit most of the key ways you’re most likely to start getting involved/encourage others to get involved. The order I’ve chosen reflects what I suspect is a fairly typical approach to finding out more about a project, particularly for those who aren’t open source savvy already, but, as they say, YMMV[2].

I’ve managed to stop myself using Enarx as the sole source of examples, but have tried to find a variety of projects to give you a taster. Disclaimer: their inclusion here does not mean that I am a user or contributor to the project, nor is it any guarantee of their open source credentials, code quality, up-to-date-ness, project maturity or community health[4].

GET methods

• Landing page – the first encounter that you may have with a project will probably be its landing page. Some projects go for something basic, others apply more design, but you should be able to use this as the starting point for your adventures around the project. You’d generally hope to find a link various of the other resources listed below from this page. Sigstore
• Wiki – in many cases, the project will have a wiki. This could be simple, it could be complex. It may allow editing by anyone, or only by a select band of contributors to the project, and its relevance as source-of-truth may be impacted by how up to date it is, but the wiki is usually an excellent place to start. Fedora Project
• Videos – some projects maintain a set of videos about their project. These may include introductions to the concepts, talking head interviews with team members, conference sessions, demos, HOW-TOs and more. It’s also worth looking for videos put up my contributors to the project, but which aren’t necessarily officially owned by the project. Rust Language
• Code of Conduct – many projects insist that their project members follow a code of conduct, to reduce harassment, reduce friction and generally make the project a friendly, more inclusive and more diverse place to be. Linux kernel
• Binary downloads – as projects get more mature, they may choose to provide pre-compiled binary downloads for users. More technically-inclined users may choose to compile their own from the code base (see below) even before this, but binary downloads can be a quick way to try out a project and see whether it does what you want. Chocolate Doom (a Doom port)
• Design documentation – without design documentation, it can be very difficult to get really into a project (I’ve written about the importance of architecture diagrams on this blog before). This documentation is likely to include everything from an API definition up to complex use cases and threat models. Kubernetes
• Code base – you’ve found out all you need to get going: it’s time to look at the code! This may vary from a few lines to many thousands, may include documentation in comments, may include test cases: but if it’s not there, then the project can’t legitimately call itself open source. Rocket Rust web framework[5]
• Email/chat – most projects like to have a way for contributors to discuss matters asynchronously. The preferred medium varies between projects, but most will choose an email list, a chat server or both. Here’s where to go to get to know other users and contributors, ask questions, celebrate successful compiles, and just hang out. Enarx chat
• Meet-ups, video conferences, calls, etc. – though physically meetings are tricky for many at the moment (I’m writing as Covid-19 still reduces travel opportunities for many), having ways for community members and contributors to get together synchronously can be really helpful for everybody. Sometimes these are scheduled on a daily, weekly or monthly basis, sometimes they coincide with other, larger meet-ups, sometimes a project gets big enough to have its own meet-ups, and sometimes so big that there are meet-ups of sub-projects or internal interest groups. Linux Security Summit Europe

SET methods

• Bug reports – for many of us, the first time we contribute anything substantive back to an open source project is when we file a bug report. These types of bug reports – from new users – can be really helpful for projects, as they not only expose bugs which may not already be known to the project, but they also give clues as to how actual users of the project are trying to use the code. If the project already publishes binary downloads (see above), then you don’t even need to have compiled the code to try it and submit a bug report, but bug reports related to compilation and build can also be extremely useful to the project. Sometimes, the mechanism for bug reporting also provides a way to ask more general questions about the project, or to ask for new features. exa (replacement for the ls command)
• Tests – once you’ve starting using the project, another way to get involved (particularly once you start contributing code) can be to design and submit tests for how the project ought to work. This can be a great way to unearth both your assumptions (and lack of knowledge!) about the project, but also the project’s design assumptions (some of which may well be flawed). Tests are often part of the code repository, but not always. Gnome Shell
• Wiki – the wiki can be a great way to contribute to the project whether you’re coding or not. Many projects don’t have as much information available as they should do, and that information may often not be aimed at people coming to the project “fresh”. If this is what you’ve done, then you’re in a great position to write material which will help other “newbs” to get into the project faster, as you’ll know what would have helped you if it had been there. Wine (Windows Emulator for Linux)
• Code – last, but not least, you can write code. You may take hours, months or years to get to this stage – or may never reach it – but open source software is nothing without its code. If you’ve paid enough attention to the other steps, got involved in the community, understood what the project aims to do, and have the technical expertise (which you may well develop as you go!), then writing code may be way to you want to do. Enarx (again)

---

1 – I did consider standard RESTful verbs – GET, PUT, POST and DELETE, but that felt rather contrived[2].

2 – And I don’t like the idea of DELETE in this context!

3 – “Your Mileage May Vary”, meaning, basically, that your experience may be different, and that’s to be expected.

4 – that said, I do use lots of them!

5 – I included this one because I’ve spent far too much of my time look at this over the past few months…