Kelli Shaver

9 months ago

Musings on open source software development.

I maintain (or assist in maintaining) a few open source projects. Over the past few weeks, I’ve noticed some common trends from people submitting code, so I’d like to take a moment to talk about it; what goes on behind the scenes on an open source project, why a project is open to begin with, and how to contribute effectively.

Why is this code open?

The first thing you have to look at when you’re considering using or contributing to any open source project is to ask yourself why that code is open to begin with. Open source code happens for a number reasons, some more altruistic than others, each equally valid. Here are just a few:

1. The developer built something to solve a specific problem and decided to share the end result. Projects like this are essentially developers being nice guys. They’ve had a very specific problem and they’ve solved it and then decided to toss the code onto the internet for others dealing with the same issue. This code is written to do something, and now it does it. Future development by the initial developer may not happen, as they’ve accomplished what they set out to do and have moved on. If this type of project hasn’t been active in six months, don’t bother contributing. Fork it and do your own thing.
2. The developer is solving a generalized problem and wants to share, for the sake of the community. This is the ideal situation to be in. The developer has built something useful that will appeal to a large audience and they have an active interest in making it better and seeing the project grow. These are the best projects to contribute to and are usually quite active and often looking for developers to lend a hand.
3. The open source project is a marketing tool. While it may sound shady, this is a perfectly valid reason for opening up your code. A company that releases open source projects will typically generate a lot of traffic, brand awareness, and community around that project. It’s a means of advertising that says “look what we can do” and may be accompanied by other services such as paid installation and commercial support offerings. While it’s certainly possible to contribute to projects like these, they are usually more tightly controlled, since the company has an image and a reputation to protect.
4. The open source code is a tool for self promotion. This happens when an individual develops something and then puts it out there, to showcase his or her talents and gain exposure as an individual. It’s similar to code open sourced by companies for marketing purposes, but there’s usually a little less red tape to contributing. These projects may not be as actively developed, due to time constraints on the individual, but while they’re still tightly controlled, most indie developers are open-minded about accepting contributions if the code and the functionality is solid.
5. The open source code was meant as a learning project. Here the developer(s) created and subsequently released code for the purposes of learning something new. These projects are often small, and may or may not be of high quality. They can be great seed projects to build ideas and larger projects from, but contributing to them directly can be tricky. A developer learning a new skill will likely be eager to accept feedback and improvements from outside developers, but may potentially lack the experience and discerning eye to filter out the bad commits from the good ones.

What goes on behind the scenes of an active open source project?

This varies a lot depending on the project and the experience level of the developers involved. Some projects fly pretty lose, others are extremely tightly controlled. One thing to keep in mind, though, is that in most cases, no one is directly making money off of their open source code. If the code is maintained by a company, then the needs of the business have to come first. If the project is ran by a team of enthusiasts, no matter how dedicated or skilled the developers are, things like paying for the kid’s braces and fixing that leak in the roof mean that paying work will always come first.

Many times an open source project may have a slow release schedule or a pause in development, or swap out core team members without explanation or obvious reason. The community may not always be privy to the reasons, because they are often personal. It is not ideal, but it is life and it’s often a necessity.

No one likes to see a project they love stagnate, and that is doubly true for the people who are responsible for maintaining it.

The main thing to remember when things like this happen is this: The code is open source. If you do not like the way the current code is being maintained, you can fork it and manage your own offshoot project.

How do you contribute to an open source project?

Let’s say you’ve found a project you love and you want to get involved. You have an idea for a great new feature and you’d like to implement it. So what do you do? Here a few tips.

1. Ask if you can get involved. Managing a team can be stressful. The project maintainers may have all of the help they want. Ask if your contribution is welcome before submitting code.
2. Work on open issues before implementing new features. Most projects have at least one or two open issues. Closing those out before adding new code will help the project remain stable, credible, and useful. It also means a better base upon which to build new features.
3. Don’t submit anything that isn’t accompanied by a working test. This varies from project to project, but for most of the projects I work on, we won’t accept anything unless it is accompanied by a working test case that shows the expected outcome and tests for common issues.
4. Follow the established style. Don’t go changing the code style or formatting conventions used by the project, don’t change the way comments are formatted, and don’t rearrange code unnecessarily. It is disrespectful to the team, highly subjective, and even worse, it can make code tracking and maintenance difficult, since it results in large diffs wherein only the spacing has changed.
5. Follow the branching model that’s already in place. This goes along with code formatting, sort of. If there’s already a method in place for branching, developing, merging, and integrating new features, stick to it. Version control is more than just a big “oh shit” button for when things go bad. Properly maintained code repositories give a thorough history of the lifecyle of the project. Commit history is important.
6. Comment on why you’re doing something, but not what. If you have to comment what you’re doing, then chances are that the code is poorly written. Explaining why you chose to do something, however, is encouraged.
7. Make good commits.This is extremely important, especially any time there is more than one person working on a project. Here are some tips:
   1. Make your commit messages thorough, with a good top line summary and further details in the body of the commit message.
   2. Don’t make unnecessary commits, either. Squash and rebase commits as-needed to make sure that your history is clean before submitting a pull request.
   3. Each commit should only address one issue. Don’t have one commit that adds a field to the user model and fixes a CSS issue in Internet Explorer.

What happens when a pull request is received?

When a pull request is received, it must then be approved before it can be merged into the project. This process can take anywhere from a few minutes to a few weeks, depending on developer availability, complexity of the code, and other work that’s taking place on the project. I do a lot of code reviews, and in general, I’ve seen fairly poor response from the contributing developer with regards to those reviews, so I’d like to take a moment to talk about them.

Code reviews are hard. They are. They’re a little like critiquing artwork, only harder. A lot of a code review is subjective, and a lot of it will relate to the work you’ve done and how it stacks up against and adds to the existing code. In the end, though, a code review is a judge of quality, and no one likes to be judged. Here are a few reasons why your code might not be accepted.

1. It’s bad code. When I do a code review, I don’t sugar-coat. If your code is crap, I will tell you it’s crap. I will do my best to explain why, but I may not always have time. Don’t confuse being honest and blunt with being rude. Don’t get your feelings hurt. Just write better code.— If I tell you that your code needs work, don’t argue. Fix the code.
2. It’s not a good fit or is too specific to your individual needs. If your code simply isn’t a good fit, you’re welcome to explain your reasoning, and I’m open to re-thinking how something should be implemented, but ultimately, just because you want to implement feature X, it doesn’t mean it belongs in the project as a whole, or that the way you implement it is a good fit.
3. The timing is wrong. Projects in active development have a lot of things going on and may be managing contributions from many outside sources. To top it off, there are a number of valid reasons in which the developers may not make the project road map public (the expectation of deadlines vs. personal obligations, to maintain a competitive edge when the code is used for marketing purposes or for securing new leads, etc.). Sometimes your code will be rejected because all of the pieces just don’t line up. When this happens, be patient. Give the developers time to reach a point where the code is stable and mature enough to accept your request. Wait until the next round of planned layout revisions is done before adding your own custom CSS, etc. Step back, wait, submit again when it’s appropriate.
4. The maintainer hates you and wants to make you suffer. This only happens after about 8 of your previous pull requests have been rejected. Seriously, though, sometimes personalities just don’t mesh. If you’re consistently getting shot down on a project, don’t continue making everyone, including yourself, miserable. Move on to something else, or fork the code.

Other thoughts

Here are a couple of random observations to finish things out. Maybe they’re not pretty, but they’re accurate and worth mentioning.

1. Open source does not always mean open development. Open source code means you’re free to download, use, modify, and often times re-distribute the code as you see fit. It does not, however, automatically mean that a project is even open to outside development or that it has to accept contributions evenly from all developers.
2. Open source code doesn’t entitle you to anything. Just because the code is released to the public, even if it becomes popular, it doesn’t mean that the original developer is under any obligation to continue development, release updates, fix bugs, or even relinquish control of the project to another person. It is essentially free software that’s being given away. Take it for what it is. Expect nothing more from it, and be appreciative of the projects where you do get more.

So there you go, some quick thoughts on open source code, what goes into it, why, and how to contribute. Maybe this will be helpful to someone. Maybe it was a cathartic rant. Either way, the main take-away should be this:

Open source projects are not maintained and managed like commercial software is developed (in most cases). FOSS is motivated by different reasons and developed under a different paradigm. Other things like bills and family take priority, and developer choice is a fact of life, whether you agree with it or not. Be respectful, ask where you can help before diving in head-first, and don’t take it personally if your code isn’t accepted into the project.

Oh, and one last thing…. just about every open source project out there needs someone who’s willing to come along and help out in the form of writing and translating documentation.