FOSS: What Will the Community Do to Me?

Open source is a great way to mildly annoy Hacker News, but sometimes accidentally gives value to someone. With permission from my work here is an edited version of a FOSS guide I wrote. You will find an overview of what to expect from open sourcing your projects, along with some good practices. This was originally intended for teams, but mostly also applies for individuals and hobby projects.

Most of the advice here will be common sense, as they are good practices in general. Any effort to make your project approachable to strangers is also beneficial within an established team.

What kind of work is worth sharing?

As a collective you have already determined which sections of your codebase are critical to your competitive advantage, and therefore must be kept secret. Everything else, I would say, is worth sharing in some form.

If you do not believe other developers could gain value from your work then you are either wrong or the work isn’t valuable to you. Projects that you share do not have to be the next Hacker News fad, or explode with stars overnight. You are offering some problem solutions that you couldn’t find elsewhere, that’s all that a project needs.

Obviously the world might survive without another FIZZ/BUZZ implementation or JavaScript framework. If your work is genuinely already solved elsewhere then maybe use this as an opportunity for self reflection, why did you build this software in the first place?

What Does A FOSS Project Need?

Short answer: All the same stuff as a regular project.

More thorough answer:

• A project root README
  • A concise description of the project purpose and goals.
  • List of dependencies
  • Build steps where applicable
  • Code examples where applicable
  • Contact information for the maintainers
  • Rules for contributing (link to coding standards etc)
  • A license declaration
• Clean layout
  • The project should be modular and self contained where possible
  • Unit tests with a good standard of code coverage (use best judgement)
• Well documented code
  • Comments where appropriate
  • README for larger isolated components of your project
  • Configuration examples (up to date!)
  • Code examples (more in depth than the README)
  • Architecture diagrams and high level design documents

What Will The Community Do To Me?

Your mileage will vary when it comes to interacting with an online community, but here are some key themes I discovered across my projects.

Initial Reception

Most likely the first thing that will happen when your repo goes public is… Nothing. Even when posting your project in various online forums you can expect to be met with very little attention.

It is important to understand that this is not a reflection on the project or the author, as it takes time for a project to gain momentum. Even if your project initially gains lackluster response, it is never more than a single post from exploding with attention given the correct circumstances.

Do not let a lukewarm reception drive you away from maintaining your project.

Feedback

A natural human reaction to being bombarded with feedback from strangers is either being defensive, overcome with woe, or both. You need to keep a clear head when reading feedback and remember that this process is meant to help you and the project improve, and not a punishment.

It is a great idea to record and respond to all feedback received, but to help you stay in control of the flow you should categorise it. I tend to split feedback into the following:

Technical Issues

Bugs and general design problems are the gold you are prospecting. This is an actual problem that needs addressing (sooner rather than later). When real problems are revealed by the community (sometimes even fixed) make sure you thank and credit those people since they have spared you from impending pain and suffering.

Documentation Issues

Most of the feedback or questions you receive will likely be due to gaps in documentation. This also includes a general misunderstanding of your project or its goals. If appropriate then use these as opportunities to update and improve your READMEs, comments etc.

Genuine and reasonable misunderstanding should be permanently dealt with, don’t just respond to the individual and move on. However, some people on the internet are just trolls or contrarians, make a judgement call.

Feature Request

Take note, some of these are great ideas and should be done, some should be rejected, others can be left as an issue with the “Help wanted” tag. These are the hardest to triage and respond to as they require thought and consideration. Do your best and be polite.

Design Disagreements

If someone has a problem that isn’t any of the above then it’s probably a design disagreement. Not everyone has the same priorities or issues as you do, some people will try and shoehorn your project into their problem space.

It’s easy to lose significant time to these conversations so try and be respectful, but do not be afraid to reject requests and feedback that you don’t feel will fit the project.

Laziness

Be wary of the fabled “Lazy Dev”, many requests may seem to fall into one of the above categories, when they are in fact a thinly veiled attempt to extract code examples or bespoke documentation from you.

Politeness is key to all community dialog, but be willing to refer some folk to the documentation or codebase when their requests are trivial.

Forks

People will fork your project. Lots. Github forks are very often used as bookmarks. If a high profile organisation forks your project they will likely contact you if they intend to do significant work to it. My advice is to ignore forks until you see a pull request.

Summary

Looking after a FOSS project is fun, extremely rewarding, and mostly common sense. The key things to get right are politeness, managing your time whilst being responsive, and keeping in mind that you aren’t working for the community, you are working together.