73

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

Arseni Mourzenko
  • 134,780
  • 31
  • 343
  • 513
Colonel Panic
  • 1,017
  • 1
  • 8
  • 11
  • 1
    [Sharing your research helps everyone](http://meta.programmers.stackexchange.com/questions/6559/why-is-research-important). Tell us what you've tried and why it didn’t meet your needs. This demonstrates that you’ve taken the time to try to help yourself, it saves us from reiterating obvious answers, and most of all it helps you get a more specific and relevant answer. Also see [ask] – gnat Aug 02 '14 at 13:20
  • 21
    The question was pretty clear, IMO. -- "What's this `Contrib` folder that I keep seeing in projects?" -- "Why, or why wouldn't a project have one?" -- "Is there some standard convention for this that I should know about?" – BrainSlugs83 Dec 05 '15 at 01:49

4 Answers4

44

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.

Bryan Oakley
  • 25,192
  • 5
  • 64
  • 89
  • 2
    This is the correct answer. – Blrfl Jan 11 '17 at 00:05
  • I've noticed also that stuff in contrib will occasionally make its way into non-contrib. I suppose the implication in this is that it has been adopted into the project mainline for more active support and development? – fostandy Mar 24 '18 at 13:20
  • 1
    @fostandy:yes, that is correct. – Bryan Oakley Mar 24 '18 at 13:32
  • It doesn't make clear if the software in contrib folder is completely external (like typically in a lib folder) or source-code only, made specifically for the project but as a "second class code" not being maintained by the core developers. – simon Jul 24 '20 at 09:25
  • @simon: the contrib file is just a convention. Some projects may use it for completely external code, some may not. There is no standard for the contrib folder. – Bryan Oakley Jul 24 '20 at 12:47
  • Could this distinction between contrib and non-contrib also apply to projects where the "main" library provides a lot of abstract classes / interfaces that can then be implemented by some of the code in "contrib"? I found this to be the case in the example of Django and am wondering if it's a worthwhile pattern to adopt in a C++ library I am building... – saxbophone Aug 04 '22 at 01:27
22

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

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.

makerj
  • 103
  • 3
Arseni Mourzenko
  • 134,780
  • 31
  • 343
  • 513
  • 2
    Actually, I was wondering exactly what a "contrib" is. Solr has then, Grunt too. Is this just another term for plugin/ add-on/ ? – Martyn Feb 05 '15 at 03:27
  • @user3265472: I edited my answer to include Solr. As for Grunt, are you talking about [this one](https://github.com/gruntjs/grunt)? I don't think there is a contrib directory. – Arseni Mourzenko Feb 05 '15 at 13:32
  • Yeh that's the one, sorry I missed folder from the question. I was tying to understand the term "contrib" myself. Grunt has various plugin/ libraries(?) named as such (Grunt-contrib-uglify, Grunt-contrib-jshint, etc). Your description given gives me a better idea though, thanks. – Martyn Feb 06 '15 at 06:11
  • The one project I *fondly* recall having a contrib folder is phpBB. The only instruction that was given was to delete both it and the installation folder after running the installer. ¯\\_(ツ)_/¯ – BoltClock Aug 26 '15 at 06:30
  • 2
    Some packages in Debian fall into a class of packages called 'contrib'. This is what the Debian Policy Manual has to say about it "Packages in the other archive areas (contrib, non-free) are not considered to be part of the Debian distribution, although we support their use and provide infrastructure for them (such as our bug-tracking system and mailing lists)." – Kevin Wheeler Aug 26 '15 at 09:27
  • 3
    Lots and Lots of OSS projects I've looked at over the years has a folder called `Contrib` (looking at yet another one right now in Akka.NET)! -- I have no idea why they have a folder named that, or what the convention for this naming convention is. -- None of the things mentioned so far seem to fit all the ways I've seen "contrib" used. -- it seems like every project has completely different stuff in there (Akka.Net seems to put a good quarter of their codebase in there: Akka.Clustering, Logging, DI, Persistence, TestKits, etc...). – BrainSlugs83 Dec 05 '15 at 01:44
  • Tensorflow has it too. – Oliver Ni Nov 24 '17 at 00:37
  • I can confirm that we use contrib/ for "additional utilities" rather than contributions from non-core engineers. – lzap Oct 08 '21 at 13:39
  • Just for the record, the committers of some files being the core devs does not necessarily mean they were authored by them. The people might be just the ones adding them to the repo from elsewhere, doing basic formatting cleanup etc. – Yirkha Jun 17 '22 at 20:10
8

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.

Amac
  • 81
  • 1
  • 1
  • 2
    I don't share this view. For what you describe, I would rather use the names `vendor` or `thirdparty`. – moi Oct 03 '19 at 06:38
7

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.

Alex W
  • 170
  • 1
  • 4