How To Turn Your Pile of Code Into an Open Source Project

Esther Schindler writes "You've written some code, you think it would be useful to the world, and you'd like to give back to the open source world. But how do you do it? Andy Lester provides a checksheet for developers for how to release an open source project and get it noticed. For instance: Before you release the project to the wild, write some documentation, create a mailing list, create an issue tracker, and so on. 'Users require releases of your software. It’s a disservice to your users to point at the Git repo and say “Just pull from the master branch and install it.” Users don’t want to have to use version control just to get a release of the code. Create a proper tarball (.tar.gz) that is easily downloadable by anyone. Announce each release. Your announcements should not assume that the reader is familiar with your project.' You think he's missing anything?"

Comments

You think he's missing anything?

[Osgeld]

yea, don't make a sourceforge page saying that "this will be" having written a grand total of a comment in a .h file

Re: You think he's missing anything?

[Anonymous Coward]

Also, he has the order wrong. First, make sure that you have something that works. Then, make sure, it is well documented. This includes both good user documentation (and not just "some documentation", good documentation is even more important than good code!), and good developer documentation, as well as a short description that tells people what your code actually if good for. (this seems trivial, but I've seen open source projects where even after browsing the web site for ten minutes or more, I still had not the slightest idea what they actually try to accomplish). Then make sure it has at least a minimal test suite. And then, write up a roadmap where you want the project to go (it may well be a very rough roadmap, but it should be there).

And if all that is done, then you can start thinking about setting up a public code repository, web site, mailing list, bug tracker, etc.

Approachable download for the way!

[billyswong]

Create a proper tarball (.tar.gz) that is easily downloadable by anyone.

Finally someone mentioned that. Git repositories asks users install extra software before even trying your code. Hate it a lot.

Re:Approachable download for the way!

[Anonymous Coward]

You can usually download archives from github and sourceforge.

Re:Approachable download for the way!

[tlhIngan]

What's in it for them? The point of releasing open source code is not to gain users, it's to gain contributors. If you're someone for whom having to download a tarball and build it is too high a barrier to entry, then you're probably not someone who is likely to contribute patches either (and if you don't already have a dev environment set up, then you're almost certainly not going to contribute code). Given that they have limited time to spend on the project, does it make more sense to spend that time catering to you, or to people who will build from source?

Users ARE contributors. First off, just using the program means they find it useful for their needs and thus find things that seem odd (aka bugs). Or insufficient (like documentation). They're also your best asset at marketing (yes, marketing - unless you want your project to die on the vine, you need to advertise and ensure it's known). Getting more people means you grow a community and the chance to attract further developers.

The problem with OSS in general it seems is that it overvalues developers at the expense of everyone else. Think "you have the source - there's the documentation!" or "don't file a bug, fix it!" type mentalities.

Unfortunately, the reality of the world is - like an author of a book, the source code isn't the only thing in the world. There's a whole world of other people with soft or non-technical skills that are required. For tiny little command line utilities, sure a lot of this isn't required (and perhaps where the mentality comes from), but larger non-trivial projects really do need contributions from technical writers, designers (especially UX), and sometimes, unrelated experts who find your program actually solves one of their problems (science is full of examples where one field inadvertently creates progress in another because the principles apply).

And sometimes, there are projects that are useful for users but the software is so mature that very little further development is needed.

Well I would say you actually try to get a few binaries.
Windows 32bit
Windows 64bit
a DEB package and RPM for Linux
and OS X.

Why would you do a 64-bit Windows build? There's very little reason to do so except:

* Your program is library that plugs into an existing 64-bit Windows program
* Your program routinely deals with huge datasets that a 3GB user area is guaranteed to be insufficient.
* Your program is a Windows device driver (which eliminates the need for Linux/OS X binaries)

64-bit Windows can run 32-bit Windows code just fine. In fact, after getting a computer where 64-bit Windows was necessary, most binaries run on it are still 32-bit - even large ones like Firefox (due to compatibility).

Prepare for Debian

[G3ckoG33k]

Prepare for Debian instead of Ubuntu so, that more users can enjoy your freedom. Starting our preparing for Debian will definitely reach out to more users. Ubuntu and Mint and many other distros are in many cases directly or indirectly based on one of the latest versions of Debian Sid. Preparing for Ubuntu directly is less attractive for that and other reasons.

Re:Prepare for Debian

[Arker]

That's bad advice. Publish a proper tarball and let Debian customise it for Debian, Ubuntu for Ubuntu, etc. Do one job well, dont try to do everything.

Build environment

[Anonymous Coward]

Clearly documenting the required build environment and tools is a must - poor build environment documentation is a huge barrier to anyone wanting to jump in and make some small (but worthwhile) improvement, thus defeating a large part of the point of open source.

Too many O.S. projects take the attitude of "it builds fine on my setup", leaving potential contributors with a frustrating guessing game trying to work out what that setup might be.

Write a clear, concise definition

[Anonymous Coward]

If you can't write one sentence that describes it and one paragraph that explains what it does, nobody will ever know what it is. Write for someone who doesn't have your experience, doesn't know how to code, but has the same problem. Specifically, include on the description page phrases that could describe the problem you're solving so that google will point people there.

The other big thing, write accesible error message. Today's best example. eLAIX is an extension to libreoffice that converts ODTs to EPUBS (see that easy to google phrase there). It barfed all over a word document that I imported into libreoffice. Known bug. However, google has no results for the error message. After an hour of searching, I figured out that it's a known issue with word documents, and that cut/paste as RTF into a new libreoffice writer will clear the whatever breaks it. If the error message had been "googleable" or the error message given a "this might be a word document import that failed" then I would have saved an hour chasing this down.

Yes, your users will break it in unimaginable ways.

And ship a goddamned executable

[Anonymous Coward]

Nobody wants to track down 85 dependencies, half of which will no longer work with the rest of the code base, in order to run whatever software you are releasing. It's 2013, and you can afford to bloat the .tar.gz file with a precompiled build. It's not like you're paying for your own bandwidth. /rant

No

[drwho]

Please don't. The world has enough crap code as it is. Unless your code is GOOD, keep it to yourself. You may think 'well, it may be bad, but someone will find a use for it' - but the very existence of bad code to solve a problem can keep goo code form evolving, as people adopt the crap. Please, fix your code before posting it for public consumption. If you can't, then find someone who can or mark it as 'crap code please fix - do not deploy!'. People will respect your for your honesty.

Re:Compiled Windows Binaries

[Anonymous Coward]

If Windows binaries aren't provided, it means no one on the dev team could get them to build. (Maybe they can't figure out how to un-#pragma the #pragging #pragma correctly?) That's a big warning sign.

Or maybe it means no one on the dev team uses Windows. Pretty much the same reason why you don't see a binary for Mac either.

What made your platform so damn special that we need to provide a binary for your platform when we don't provide binaries for any other platform?

Re:Compiled Windows Binaries

[Samantha Wright]

How does "not remotely POSIX compliant and hence generally not source compatible" sound?

Re:No .tar.gz, Get a package manager

[Arker]

If it's in any way difficult for you to install from a proper tarball then there is something wrong. Perhaps you should try a sane distribution?

Re:Compiled Windows Binaries

[Samantha Wright]

Hey, you're welcome to say Windows isn't supported. That's totally your choice. Just don't say something is supported when it isn't. There are a lot of half-assed OSS projects out there that do this. (That being said, you don't need the hardware; VMware Player is close enough to native performance. And to some extent, even WINE and ReactOS can provide an alternative to getting a Windows licence if the software's simple enough.)

Re:No .tar.gz, Get a package manager

[TheRaven64]

The tarball is not for casual users. The tarball is for packagers. Having a stable tarball (i.e. one with a published URL whose hash won't change between downloads) makes it much easier to create the package.

Re:Compiled Windows Binaries

[Anonymous Coward]

What made your platform so damn special that we need to provide a binary for your platform when we don't provide binaries for any other platform?

Other than a 95% market share, nothing.