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...)
What about DEB/RPM files? Not everyone wants to build everything from source.
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.
GPL, LGPL, MIT, etc etc
It's your code.describe best how to test it, log it and bug it so it won't go untended as it grows.
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.
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.
I deliberately eschew tarballs. Especially for a young project, having the repo bootstraps the contribution process. Found a bug? Fork it and issue a pull request. Even if the maintainer gets hit by a bus at least you now have a sane way of tracking your customizations and bug fixes.
It's infinitely more useful. Tarballs make me think of shitty sourceforge days.
Packages OTOH can be nice. Until you can't figure out where the hell the Ubuntu package maintainer decided to put the config files. Until you're affected by a bug and need a bleeding edge release. Then you're back to downloading and compiling from source (or finding a 3rd party PPA) anyway.
In fact, I'd encourage others to compile from source so that you can work out any discrepancies there. For an open source project you want to breed as many contributors as you can. Get as many people running your test suite as you can in case there's oddball environment differences that mean you're the only person alive capable of compiling it.
Tar.gz is nice, and .deb is even better, but the hard truth is that most users use windows, so you really need to publish an MSI or an EXE.
Look into WiX or NSIS to create an installer for Windows.
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
Some of us are more paranoid than others. I prefer my software to be signed with PGP, or at the very least, accompanied by a SHA-2 hash. It disappoints me how few open source projects regularly do this.
It's nice to set up mailing lists, etc., but it's hardly something you should feel any obligation to do. If you have a relatively small, well-written, self-documenting library or utility, it's already a gift. If you've finished with the code, and you're no longer willing to invest time and effort beyond bug fixes, well, maybe that's an opportunity to take donations, or leave it in the wild for others to do with it as they please.
He he. Ha ha ha. HAHAHAHA! Oh, my lord, that killed me. Ahhh, too funny. Oh my goodness, my sides hurt. Please, no, here I go again... HAHAHAHAHAHA!
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!
In most cases it's easy if you already know how and have the environment set up.
So...basically nobody. Way to alienate a lot of potential users.
No sig today...
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.
Just having a mailing list is not enough, you need to build a community, which means 1. you need to be active on that mailing list and 2. provide support as well.
To get your project noticed, you'll likely have to shamelessly promote it. Your project is probably not the only one of its kind (typically, you're not that special). If you're building an open source alternative to a closed source project, you may want to join an existing mailing list of the closed source project to humbly announce your own; this worked well enough for Linus' little OS kernel as well, if I recall.
You may want to go a few steps further than releasing on git or building a tar ball. Releasing pre-compiled versions Windows and Mac can contribute greatly to the success of your project. Just think where popular open source projects such as Firefox would be if their users had to compile it themselves.
Write a manual, and make it available online - ideally not (only) as PDF but as a set of HTML pages. Users are not going to read it - most of them anyway, but you'll be able to link to the relevant sections when responding to frequently asked questions so you don't have to waste too much time supporting your software. Just don't be arrogant about things, "Jeez can't you people RTFM?" is quite blunt.
Finally, that song "Sing" is actually not from Sesame Street but by the Carpenters.
...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?
How does "not remotely POSIX compliant and hence generally not source compatible" sound?
Bio questions? Ask me to start a Q&A journal. Computer analogies available for most topics!
How does "not remotely POSIX compliant and hence generally not source compatible" sound?
It sounds like your platform sucks, that's how.
If you want me to provide a binary for your crappy platform, are you at least willing to donate the money needed so I can purchase a license for the platform? Maybe even money for hardware too.
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!
Pick your FOSS license and get that code out there, don't wait. You can do all that other stuff, but if you want to contribute, get your code out there now!
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.
Against Lester's suggestion, do not use a Wiki. I have seen way too many projects with a half-baked or even empty Wiki, since the programmer believed that if he created a Wiki, the documentation will be written "magically" by the users. That is not going to happen, period. The one and only who can actually write the documentation (be it the API spec, examples or user manual) is you, the original programmer. Everybody else is just a beginner...
"Fix it? It has been disintegrated, by definition it cannot be fixed!" - Gru in Despicable Me.
Actually most software you can compile on Linux using MinGW64 and do a basic test using WINE.
Yes, your users might run into unexpected issues. But if you want your project to be popular it is a good thing to do, getting a development environment working on Windows is a pain even for advanced users IMHO. And yes, that is entirely Window's fault, the reason Windows works reasonably well is because of all the people investing time into working around its issues.
And concerning tarballs: git often allows you to download snapshot tarballs directly from the web interface.
So many bad open source projects come from the author underestimating the work in making a project work. It's easy to think "hey I wrote this, somebody gotta find it useful" It's a huge amount of work to make it an effective project. And you have to ask WHY you want to do this - it's a similar amount of work to making your software a viable commercial prospect, which would have the added benefit of putting food in your cupboard. His suggestions are a good start, but in this day and age you need to do more. For example, you really need video tutorials of your software. And once you start putting them together, you start to see more shortcomings in your software, so you stop the video, make some coding improvements, and continue. This is a long process! A lot of people think "hey, when people see this, I'll get contributors to help me" But if you really want things to work out, you need to project manage the contributors. Everyone has their own priorities, and the project lead needs to get everyone working in the same direction. And you've got some tough decisions. If someone sends you a useful patch that's lacking in tests and documentation, what do you do? It's a pain to reject it, but a pain to accept it too. What the project really needs is leadership, and that is a massive commitment.
Think again. why REALLY why do you want to put your source on the internet?
-Recognision. Your name? --> Then only post excellent code.
-To get some work done? -> post it, document it, expect notthing.
-Someone lese to debug your code? -> unlikely, but possible. Users are more likely to recompile and look for the
#define NUMBEROFBUGS 9
and change that value. Making a good build environment available helps a lot if you want more people compiling your code. Please include as much depenancies in your tar.gz as possible, even if that is not your code.
Do not expect miracles however. For every 1000 binary downloads, 30 people will bitch about the colors, 20 will put in feature request that are not feasable, 10 people will download the source, 5 will compile it, and 1 will give you really useful feedback on the source or patch it.
You can focus on makeing that "1000" number much bigger, or make the percentage of usefule feedback better. The latter requires documentation.
TFA really should be required reading for anyone developing a significant open source project. An area which seems particularly in need of help is OS projects in the sciences. Some are very good, but others (sometimes important ones) fail most of the items on the list. They end up being developed by one or two people, no mailing list, minimal docs, no issue tracker, and erratic to zero response from the developer(s). The result is that others download the code, fix the obvious bugs or implement improvements, but these fixes never get incorporated back into the original project because there's no mechanism for doing it. Everyone's reinventing the wheel.
soylentnews.org
Other than a 95% market share, nothing.
I think another step is to set up a donation account and cross your fingers for donations. In this respect, may be a PayPal account would do, although they require you to do legal paperwork to register as a non-profit, or else pay higher fees. It would be great to have better _world-wide_ alternatives.
I have an open source project and people often sends me emails to my personal account instead of the community account. At first, I forwarded the emails to the community, but then I realized that it was a terrible practice as I never knew how confidential their information was. Nowadays, whenever I get an email to my personal account, I ask for donations if they wish to keep it confidential. Otherwise, I ask them to please forward the email to the community instead. I think it makes sense as I do not want to repeat myself over problems others have already had.
Create a proper tarball (.tar.gz) that is easily downloadable by anyone.
Oh and create a tarball that extracts in a subdirectory and not in the current one
Am I the only person who is put off by having to use mailing lists to communicate within open source projects?
Create a proper tarball (.tar.gz) that is easily downloadable by anyone
How much people still seem to think that OSS is still only for *nix / BDS flavor of OS's.
Oh, hmm. I don't think I've actually written the process thingy up as a library yet. I probably should. It's a bit nicer than system(). Then all those bad programmers out there could do process_thingy("rm /tmp/some_file").wait() instead of system("rm /tmp/some_file"). That's a HUGE improvement. I'll add that to my to-do list for the weekend. Funnily enough I wanted exactly such a library a couple of jobs ago, but they were using Java for their application, and it's impossible to do this in Java without JNI. And my position is if you're using JNI in your java program, you've already defeated the reason you used java in the first place (Write once, run anywhere.) So you may as well use C for the entire project.
I DID write my socket thingy as a library though, and posted it as a repo on github. You just implement a class that takes its owner, a file descriptor and a sockaddr_in pointer as constructor parameters and overload operator() to do work against the the file descriptor. Mostly it's an academic exercise, but I'll be leveraging it to do some neat things in the coming weeks. It uses pthreads and network socket I/O. Good luck getting that to compile on windows (Maybe you can with cygwin *shrug*.) I don't actually compile any code up there though. It's mostly just up there to illustrate how to do something. Maybe one of these days when I've done enough libraries like that, I'll write a book.
Oh, yeah, and I don't do windows. I think that's what I was going to say right out the gate. Sorry about that. My bad.
I'm trying to teach myself to set people on fire with my mind... Is it hot in here?
FYI, it's "needs solving" or "needs to be solved". "Needs solved" is not valid English, and makes you sound uneducated (that's not meant to be an insult, just a FYI).
ALL my code is GOOD!
I have a small bit of of software that I think is pretty useful. However, the company that created it many years ago is long since out of business. As I understand it, the company's intellectual rights and other such software was acquired by a lawfirm of some sort. I've spoken with them about it, and they no longer have the original source code to the software, so they have no way to update and maintain it or create updates for it. I told them that its such an old piece of software that its very easy to decompile; we could just decompile and then move forward using that. But they said that even so, they still have no interest in making any attempt to do this because its just not something that they see as a profitable endeavor. So that pretty much makes it shelved and abandoned.
So what I'm wondering now is if I would be breaking any laws or putting myself at risk of getting sued if I decompiled it and then created an open source project using the decompiled code.
Comment removed based on user account deletion
How much software will compile out of the box in sourceforge without entering the D Hell Hell ?
20 % ? less ?
When I said 10% I mean on Linux X86. For other platforms (which are supposed to be supported) it should be 5% or less.
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.
...it is 2013. A mailing list is 1980's shit. Open source projects with mailing lists are ridiculous.
host your project on gitlaunchzillaforgepad.com that will deal with every aspect for you.
automatic build on x platforms (bin +doc in pdf/htm/chm/ebook...)
PPA sources for bin/sources
wiki
mailing list
irc
bug tracking
announces of new major versions or events on selected sites
donation/crowdfunding
webconf (blueprints)
Actually means create an empty wiki.
I don't know how many open source projects have little to no real documentation and just a bunch of community driven wikis and message boards (usually complaining) about the project.
BTW aren't there services like SourceForge ang GitHub all set up to let you publish open source projects? I mean it sounds Andy Lester is about 10 years behind and fucking clueless of how people really publish open source code ( wtf is a mailing list in the 21st century?) Nobody wants you to pump their email with hundreds of useless messages, it the reason why RSS, wiki and community message boards were created in the first place, to supercede mailing lists.
Why are open sourcers forever looking for a new way to do the same thing someone else has already solved?
I haven't thought of anything clever to put here, but then again most of you haven't either.
The headline talks about a pile of code but the article is about assembling a project. They're not necessarily the same thing and I find great value in unfinished code. Yesterday I spent four hours trying to figure out why a simple mysql stored procedure had stopped working. This morning after reading slashdot I realized I was going about it backwards. The stored procedure was open-source. A quick google code search came up with four projects using the function. One of them had been updated. A quick read of the updated version and I understood what had changed. Copy, paste, done. The reference code was not documented or released, but it was open-source.
I do not block ads. I do block third party scripts.
Not for servers...
If it's graphical then include a screenshot or better yet an online demo.
When I'm searching for a project the number one thing I'm looking for is
whether it will fill my current need. The number two thing is whether it
is more than just an alpha project. An online demo answers all this and
more. I really don't care if something is somewhat complex to install
AFTER I decide that it's worth using but I'm not going to spend a lot of
time trying to find dependencies, etc... for software that might not even
be what I want or need.
To be fair, GCC is a cross-compiler unlike the compilers MS produces.
Testing it is another matter, I am not sure testing Wine is good enough to say your app will run on Windows.
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?
Because Windows users are pants-on-head retarded.
"I could have done more . . . open source!"
Your one man pet project on SF isn't touching my servers, don't worry.
As long as it's git or Mercurial.
Speaking as a user myself, nothing pisses me off more when trying to get some piece of software and finding I can't get it from git or hg. It simplifies my life, since I will inevitably have to patch deficiencies or bugs in the software, by using git to pull the source instead of a tarball, it makes it far easier for me to track local changes, to generate patches for sending upstream and to get updates and takes less bandwidth in a lot of cases*.
Github is great it has issue trackers and wiki built in, and I don't care for some project that would rather waste time making fancy but useless websites than work on the code. Documentation is great, when it's up to date and correct, which it seldom is. Code on the other hand doesn't lie, it is what it is.
Of course, totally sucks when a project uses svn, but then you know the code is going to be low-quality to medium-quality at best because of all the problems using svn will inevitably introduce to the development process itself, with it's one-big-merge model, totally broken.
* at the cost of more bandwidth for the initial pull.
I didn't know the answer myself so I investigated. We've never done this before, but yes: with a bit of glue it is possible. Please take a look here. It's just a quick functional prototype. Let me know if you need a boilerplate for a larger code.
Computer simulation made easy -- LibGeoDecomp