Slashdot Mirror
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?"
yea, don't make a sourceforge page saying that "this will be" having written a grand total of a comment in a .h file
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.
Just releasing a .tar.gz is not enough for most users. To ease adoption of your "amazingProjectX" you really need to package it so someone can just yum install X || apt-get install X ect.
While I personally dont mind rpmbuild myself other tools exist like FPM (https://github.com/jordansissel/fpm). After that get it into a repo like fedora/epel/etc and your users will love you (maybe...)
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.
And bear in mind that the license you choose may impact your target audience. Many devs who may want to use your project are working for companies in which the dev has little or no say about what licenses are acceptable. (Permissive licences like MIT/BSD/Apache2.0 are more likely to be acceptable, whereas in my experience GPL is more likely to meet resistance, or even immediately block people out).
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.
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.
*wink*library for computer simulations *wink*
Computer simulation made easy -- LibGeoDecomp
Oh yeah, just let me download and build all these libraries your project requires... oh, what's that? One of the libraries requires Visual Studio 2003 Ersatzpress Edition to compile? And another one needs gcc-mingw-0.0.1-super-alpha-pre-release-dinosaur-version? Okay, let me just... get on that...
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.
Bio questions? Ask me to start a Q&A journal. Computer analogies available for most topics!
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?
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.)
Bio questions? Ask me to start a Q&A journal. Computer analogies available for most topics!
It can be very difficult. My scientific plotting package, veusz, was written using Python and Qt, so it should be easily portable. However setting up a sensible developer environment on Windows to compile the Python C extensions was a nightmare. Windows is pretty developer-hostile if you're used to Linux. Trying to find and install the correct version of Visual Studio Express was difficult. I had to learn far too many things about the registry, DLLs, building installers, etc. Mac OS X was rather more difficult, however. You have to download the massive Xcode and the non-standard way that Mac OS packages executables and libraries was very difficult to understand. It took a long time to get fat binaries working.
You do get a different class of user on Windows and Mac OS X, however. The Linux people are closer to being knowledgeable about development, whereas Windows and Mac OS people are primarily users, wanting more help and hand-holding.
Solve a problem that needs solved.
For example, a guy wrote a Microsoft LAN Manager clone and talked about it on usenet. I spent six months harassing him to get the source pulled together and released so that I could run it on an Ultrix box for a lab full of AT&T PCs that our lab got as part of a grant from AT&T. The guy's name was Andrew Tridgell. His first message to me after that was "Help! I can't handle the volume of email I'm getting asking about it now!", so I suggested he set up a mailing list and let the people talk to each other instead of him.
But it all started because he wrote code that solved a problem I needed solved, and then talked about it in a forum I happened to read. Without actually solving a problem, it would have gone nowhere.
So your number one mission: Solve a problem that needs solved. Otherwise, you are just navel gazing.