What's in the "contrib" folder?

Question

Often open-source software projects have a folder called "contrib". For example, Django has one. What is it for?

Answer 1

It is for software that has been contributed to the project, but which might not actually be maintained by the core developers. Naming it "contrib" or "Contrib" is a long established convention, but there's really nothing special about the name, and it's usually only used by fairly large projects.

Answer 2

Looking at popular open source projects which come in mind, I see no mention of any “contrib” folder:

• jQuery,
• Express,
• Sass,
• LESS,
• MongoDB,
• Redis,
• Puppet,
• Chef
• NUnit,
• Ruby on Rails,
• Laravel,
• Jenkins,
• Clojure,
• Ruby.

The only one which has a “contrib” folder is Django. For Django, the role of this folder is already explained in the documentation:

Django aims to follow Python’s “batteries included” philosophy. It ships with a variety of extra, optional tools that solve common Web-development problems.

This code lives in django/contrib in the Django distribution. This document gives a rundown of the packages in contrib, along with any dependencies those packages have.

Chapter 16 of The Django Book contains a more detailed description of the role of this directory and the list of contents.

Another example is Solr. With gitstats, we can get the statistics about the contributors.

Robert Muir         22.09%
Michael McCandless  13.60%
Mark Robert Miller   9.73%
Uwe Schindler        8.17%
Yonik Seeley         5.56%
Steven Rowe          5.55%

Then, we can select only the contrib directory by running:

git filter-branch --subdirectory-filter solr/contrib --prune-empty

and get the statistics one more time:

Robert Muir         19.62%
Steven Rowe          8.87%
Mark Robert Miller   8.33%
Uwe Schindler        8.06%
James Dyer           7.80%

So the top authors are practically the same, which means that those are not contributions from the outsiders. Looking at the directories inside contrib folder, it seems that once again, those are “a variety of extra, optional tools”, exactly as in Django. For instance, you don't need the Data Import Request Handler to make Solr work, but if you want to import data from database or XML, it's nice to have it in contrib folder. Same for map-reduce, you may not necessarily need it, but there are cases where you do.

Are those plugins or add-ons? I wouldn't use this term. Plugins and add-ons have a specific integration with the main application. For instance, a plugin is not expected to run standalone, but hosted within the main application. On the other hand, contrib contains tools which can probably run standalone.

Answer 3

It's meant for libraries or components that contribute to the project, but aren't owned or a part of the project itself. I've always used it as a common or shared location to put any third-party libraries I'm using.

For instance, you might have:

• /Contrib/log4net-x.x.x
• /Contrib/SSH.NET-x.x.x
• /BackendService
• /DesktopUI
• /GenUtils
• /SMCore
• /WebUI

Then reference them in each of the project components using relative paths, so there isn't any kind of setup or config needed to prior to building it. It will build straight out of the repo no matter where it's checked out locally.

Answer 4

Git is a great example of open source software that uses this convention:

https://github.com/git/git/tree/master/contrib

Here's a relevant excerpt from that README.md file:

Contributed Software

Although these pieces are available as part of the official git source tree, they are in somewhat different status. The intention is to keep interesting tools around git here, maybe even experimental ones, to give users an easier access to them, and to give tools wider exposure, so that they can be improved faster.

I am not expecting to touch these myself that much. As far as my day-to-day operation is concerned, these subdirectories are owned by their respective primary authors. I am willing to help if users of these components and the contrib/ subtree "owners" have technical/design issues to resolve, but the initiative to fix and/or enhance things must be on the side of the subtree owners.