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...)
Some of those things can come after it got released. You probably want to build a community around it, and that community could do some of that work, or have better ideas and feedback on how to do them. Be sure that don't contain anything that is not meant to be public, release and announce it. You could build some momentum before releasing it, gathering people very interested on it as betatesters or to give feedback before going fully public. I.e. Docker had some showing in presentations giving a hint of what it did, and how, and some weeks later released the base code, and documentation, tutorials, extra tools, and community contributions piled up with time. Delaying till everything is ready and perfect risk not releasing it at all.
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).
Any distro with a repository, its up to the distro package managers.
In some cases this is the developer of the software, but usually not. Dependencies can be tricky.
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
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
Writing (and maintaining) good documentation can easily take as much time as writing and testing the code, if not longer. But it's worth doing. Please, please document. Many more people will flock to your product, in turn giving you more influence and fame. It's worth it!
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.
...He didn't mention how to choose an appropriate software license!
That's definitely something that impacts the popularity of any open-source project.
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.
Tarballs make me think of shitty sourceforge days. Packages OTOH can be nice.
Tarballs are the input for most packaging systems. If you don't publish a tarball, then I have to create one before I even start packaging your code. So you get moved to the bottom of my list. And that's probably fine for a fast-moving project, where you don't want people running an old version and sending reports for bugs that are already fixed, but for a more mature project make sure you make life easier for packagers. That means:
If you provide all, or even most, of these then I can probably package your software in 5-10 minutes.
I am TheRaven on Soylent News
Other than a 95% market share, nothing.
That platform might not be so special, which is one of the main reasons to provide the binaries. (relative) Homogeneity is one of the strengths of that particular platform. Compiling software isn't a part of most Window's users workflow - if you truly are win-compatible (and know because someone has actually compiled it), providing the binaries will give your project visibility you wouldn't have otherwise. It is a sacrifice that you can make to really contribute your software to a large group of people.