Things in contrib should not be wired into your build system, shouldn’t be part of your automated testing, shouldn’t be included in your documentation, and should not be installed with your packages.
If a thing in the source repository isn’t part of the build system, not mentioned in the docs, and not installed by default, is it really part of your software? And if it’s not really part of your software, should it be in your source-repo, taking up space and cluttering the commit log? Do you accept bug-reports about contrib stuff?
I feel like the contrib directory was at its peak in the days when software was posted as .shar archives to comp.unix.sources and any random person who found a release had no way to find more context about it - the contrib directory was effectively a curated snapshot of ideas that had come up in previous discussions, since lost to time. These days, however, all the little helper-scripts and variant patches and things can be stuck in the project’s wiki, or in blog-posts, and they don’t (as easily) get lost because these days we have search engines.
I also don’t feel the contrib directory is a good fit for maintainer-only scripts like “bump the version”, because realistically that wasn’t contributed by a third-party, and it is tested regularly, hopefully as part of the CI/CD pipeline. I’ve seen such scripts live in an “admin” directory, or just plain “bin”.
That said, I absolutely agree that developers should encourage users to share their helper-scripts and addons - such examples help prospective new users figure out what your software can do, and the more people talking about your software, the more likely it is to find its user-base.
Agree. I think the contrib directory is papering over the fact that most people only look at code. Wikis are often unmaintained or empty, so few people reflexively check them. It feels like there’s a better mechanism waiting to be discovered.
These days, however, all the little helper-scripts and variant patches and things can be stuck in the project’s wiki, or in blog-posts, and they don’t (as easily) get lost because these days we have search engines.
Search engines have been getting worse for finding things like variant patches and helper scripts in old forgotten blogs. A lot of old blog posts have been deleted from Google’s archives, it seems, because you can search for verbatim excerpts from them and get back ‘no results found’.
Rather than ask ‘why have contrib when a wiki will do?’, ask ‘why have a wiki when contrib will do?’. A contrib directory is really easy to set up.
Have a look at the description here for git’s contrib: https://github.com/git/git/tree/master/contrib. I don’t think you could accomplish this kind of thing using a wiki without changing the culture of a project towards a wiki-centric one. That’s fine, there are projects that organise everything using a detailed wiki that’s explicitly for their developers, but that’s not most projects.
Does this read like something that anyone can edit without permission or patches, or like that’s the intent?
If you have new things to add to this area, please first propose
it on the git mailing list, and after a list discussion proves
there are some general interests (it does not have to be a
list-wide consensus for a tool targeted to a relatively narrow
audience – for example I do not work with projects whose
upstream is svn, so I have no use for git-svn myself, but it is
of general interest for people who need to interoperate with SVN
repositories in a way git-svn works better than git-svnimport),
submit a patch to create a subdirectory of contrib/ and put your
stuff there.
I use this for “random scripts and examples that might be helpful to some people but not something that should be distributed as part of the software”: https://git.zx2c4.com/wireguard-tools/tree/contrib
These aren’t things I’d want to ship to users, but I know that they’ve been useful to at least a handful of people building other software or setting up various systems.
I wonder what the right level of maintenance here is. There can’t be too much maintenance, as the post notes, or else it should be part of the project. But I’ve seen cases where there is basically none at all, and then the contrib directory bitrots towards uselessness: you’re on release 6.0, but contrib is full of stuff that hasn’t worked since 4.0 or 3.0, due to breaking API or CLI changes.
I think with contrib you step into the world of issues. Stuff already mentioned by @mjn, but then it is also how varied documentation will be in the contrib. Having a contrib directory means you will aim at producing software that is compatible with these pieces of software, but that is rarely true in longer and older projects. It becomes itself a hell to research and study.
Wikis are much more clearer as they go over peer review, and aim at explaining already existing parts of software and in case of incompatibility somebody will go out of their ways and speak out and what changes are needed.
Drew generally has very unique vision of software, but all this elements together are so uniquely his that his personality invades anything he does. Then, it does that in a way that if someone has been used to different way, they are again going to suffer. Unmaintained part of project sourcecode also sounds like a nice liability as are you in control of contrib, or are you not? This liability alone in my opinion makes argument for contrib much weaker.
Wikis are much more clearer as they go over peer review,
I don’t really understand this claim. Perhaps you’re better at using wikis than I am, but I’ve never been able to figure out a good way to get a feed of all the edits on a wiki in a way that’s easy to go through, at least with MediaWiki. I have no doubt it’s possible but it seems like a pain. Really the point of a wiki is that anyone can edit it without having to get it reviewed first. Perfect for documentation, but not great for code.
In contrast, anything added to any free software project’s repository has to go through the mailing list (or pull request, etc.) where it goes through actual peer review.
Drew generally has very unique vision of software, but all this elements together are so uniquely his that his personality invades anything he does. Then, it does that in a way that if someone has been used to different way, they are again going to suffer.
I don’t think he does. Using mailing lists and email to maintain free software projects is a strategy as old as free software projects are. contrib directories are not new either. If anything I’d say the way he advocates doing it is the standard, default way of going about things and the GitHub approach is the quirky new way.
I don’t see how anyone is going to ‘suffer’ because they add a contrib directory to their project. It’s something people have done for yonks.
Unmaintained part of project sourcecode also sounds like a nice liability as are you in control of contrib, or are you not? This liability alone in my opinion makes argument for contrib much weaker.
Even bringing up the word ‘liability’ seems absurd to me. There’s no liability, there are no guarantees, it’s free software.
If a thing in the source repository isn’t part of the build system, not mentioned in the docs, and not installed by default, is it really part of your software? And if it’s not really part of your software, should it be in your source-repo, taking up space and cluttering the commit log? Do you accept bug-reports about contrib stuff?
I feel like the contrib directory was at its peak in the days when software was posted as
.shararchives to comp.unix.sources and any random person who found a release had no way to find more context about it - the contrib directory was effectively a curated snapshot of ideas that had come up in previous discussions, since lost to time. These days, however, all the little helper-scripts and variant patches and things can be stuck in the project’s wiki, or in blog-posts, and they don’t (as easily) get lost because these days we have search engines.I also don’t feel the contrib directory is a good fit for maintainer-only scripts like “bump the version”, because realistically that wasn’t contributed by a third-party, and it is tested regularly, hopefully as part of the CI/CD pipeline. I’ve seen such scripts live in an “admin” directory, or just plain “bin”.
That said, I absolutely agree that developers should encourage users to share their helper-scripts and addons - such examples help prospective new users figure out what your software can do, and the more people talking about your software, the more likely it is to find its user-base.
Agree. I think the
contribdirectory is papering over the fact that most people only look at code. Wikis are often unmaintained or empty, so few people reflexively check them. It feels like there’s a better mechanism waiting to be discovered.Search engines have been getting worse for finding things like variant patches and helper scripts in old forgotten blogs. A lot of old blog posts have been deleted from Google’s archives, it seems, because you can search for verbatim excerpts from them and get back ‘no results found’.
Rather than ask ‘why have contrib when a wiki will do?’, ask ‘why have a wiki when contrib will do?’. A contrib directory is really easy to set up.
Have a look at the description here for git’s contrib: https://github.com/git/git/tree/master/contrib. I don’t think you could accomplish this kind of thing using a wiki without changing the culture of a project towards a wiki-centric one. That’s fine, there are projects that organise everything using a detailed wiki that’s explicitly for their developers, but that’s not most projects.
The main point of a wiki is that anyone can edit it without permission or patches.
Does this read like something that anyone can edit without permission or patches, or like that’s the intent?
Sorry; I missed the link in your post and was mostly responding to the logic in the original story.
I use this for “random scripts and examples that might be helpful to some people but not something that should be distributed as part of the software”: https://git.zx2c4.com/wireguard-tools/tree/contrib
For example, there’s a little syntax highlighter program that might form a useful basis of a thing for other software that wants to show pretty config files: https://git.zx2c4.com/wireguard-tools/tree/contrib/highlighter/highlighter.c And here’s a little javascript thing for generating config files in the browser: https://git.zx2c4.com/wireguard-tools/tree/contrib/keygen-html And here’s a very basic PoC to illustrate how NAT hole-punching works with wg: https://git.zx2c4.com/wireguard-tools/tree/contrib/nat-hole-punching There are plenty others too.
These aren’t things I’d want to ship to users, but I know that they’ve been useful to at least a handful of people building other software or setting up various systems.
I wonder what the right level of maintenance here is. There can’t be too much maintenance, as the post notes, or else it should be part of the project. But I’ve seen cases where there is basically none at all, and then the
contribdirectory bitrots towards uselessness: you’re on release 6.0, butcontribis full of stuff that hasn’t worked since 4.0 or 3.0, due to breaking API or CLI changes.I think with contrib you step into the world of issues. Stuff already mentioned by @mjn, but then it is also how varied documentation will be in the contrib. Having a contrib directory means you will aim at producing software that is compatible with these pieces of software, but that is rarely true in longer and older projects. It becomes itself a hell to research and study.
Wikis are much more clearer as they go over peer review, and aim at explaining already existing parts of software and in case of incompatibility somebody will go out of their ways and speak out and what changes are needed.
Drew generally has very unique vision of software, but all this elements together are so uniquely his that his personality invades anything he does. Then, it does that in a way that if someone has been used to different way, they are again going to suffer. Unmaintained part of project sourcecode also sounds like a nice liability as are you in control of contrib, or are you not? This liability alone in my opinion makes argument for contrib much weaker.
I don’t really understand this claim. Perhaps you’re better at using wikis than I am, but I’ve never been able to figure out a good way to get a feed of all the edits on a wiki in a way that’s easy to go through, at least with MediaWiki. I have no doubt it’s possible but it seems like a pain. Really the point of a wiki is that anyone can edit it without having to get it reviewed first. Perfect for documentation, but not great for code.
In contrast, anything added to any free software project’s repository has to go through the mailing list (or pull request, etc.) where it goes through actual peer review.
I don’t think he does. Using mailing lists and email to maintain free software projects is a strategy as old as free software projects are. contrib directories are not new either. If anything I’d say the way he advocates doing it is the standard, default way of going about things and the GitHub approach is the quirky new way.
I don’t see how anyone is going to ‘suffer’ because they add a contrib directory to their project. It’s something people have done for yonks.
Even bringing up the word ‘liability’ seems absurd to me. There’s no liability, there are no guarantees, it’s free software.