Forgot your password?
typodupeerror
Open Source Programming

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

Posted by Soulskill
from the learn-how-to-swear-at-people-on-mailing-lists dept.
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?"
This discussion has been archived. No new comments can be posted.

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

Comments Filter:
  • by Osgeld (1900440) on Tuesday September 10, 2013 @11:36PM (#44816249)

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

    • by Anonymous Coward on Wednesday September 11, 2013 @03:22AM (#44817067)

      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.

  • by billyswong (1858858) on Tuesday September 10, 2013 @11:36PM (#44816251)

    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.

    • by Anonymous Coward on Tuesday September 10, 2013 @11:55PM (#44816331)
      You can usually download archives from github and sourceforge.
    • I think "tarball" makes very few people enthusiastic. Most people run windows (honestly people who know what "tarball" is are a rounding error) and prefer a zip or installer for applications, and a zip or package (nuget/npm/gem/etc) for source. When running Linux I don't care whether I get a git repo url or a tgz, they are about equally cumbersome.
  • by Kahn_au (1349259) on Tuesday September 10, 2013 @11:37PM (#44816257)

    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...)

    • by Anonymous Coward

      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 [wikipedia.org] or NSIS [wikipedia.org] to create an installer for Windows.

    • by Arker (91948) on Wednesday September 11, 2013 @02:51AM (#44816993) Homepage

      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?

      • Sorry, but it *is* difficult to get from a compilable program to a distributable program that Linux users can try out easily.

        You suggest tarballs, meaning configure && make && make install. That means you need to deal with automake and friends which are insanely obscure and hard to learn.

        The alternative is to make packages and get them into the offical repos. You have to do that for a couple of distributions, and probably test the installation on them as well. That is a large effort for a de

        • by Arker (91948)

          "Sorry, but it *is* difficult to get from a compilable program to a distributable program that Linux users can try out easily."

          A bare assertion with no logic or evidence behind it that directly contradicts experience.

          "You suggest tarballs, meaning configure && make && make install. That means you need to deal with automake and friends which are insanely obscure and hard to learn."

          What 'deal with?' What on earth do you mean. You type a command and press enter, a command simple enough you embe

          • "You suggest tarballs, meaning configure && make && make install. That means you need to deal with automake and friends which are insanely obscure and hard to learn."

            What 'deal with?' What on earth do you mean. You type a command and press enter, a command simple enough you embedded it in your first sentence. If that is 'difficult' for you to 'deal with' I suggest you try something a little simpler than a general purpose computer.

            I was consistently talking about the developers perspective, not the user! You ignored the reference to automake which made that obvious. If you think editing configure.ac and Makefile.am files is easy to learn, I bow to your brilliance, but myself and many others don't share this experience.

            And anyway I said only tarballs I didnt say anything about source tarballs. Binary tarballs are another very easy way to install a program, even easier than source tarballs, although compatibility may be more limited.

            "The alternative is to make packages and get them into the offical repos. You have to do that for a couple of distributions, and probably test the installation on them as well. That is a large effort for a developer."

            No, as a developer, you should not be making packages (except possibly for the distro you personally use.) Many distributions these days are crufty with proprietary junk and keeping up with all the little peculiarities of each distribution IS actually a lot more effort than typing 'make'. That job is best left in the hands of people who are intimately familiar with their distribution and have the motivation to tolerate its insanities.

            Binary tarballs, as you say, are limited/useless, and don't solve anything (dependency hell, different architectures). Nor is it clear where each directory is supposed to go to (e.g. libs), as this is distribution-speci

            • by Arker (91948)

              "I was consistently talking about the developers perspective, not the user! "

              OK.

              "If you think editing configure.ac and Makefile.am files is easy to learn, I bow to your brilliance, but myself and many others don't share this experience."

              I dont think it's any harder than lots of other things that developers have to do routinely. Certainly in my experience it is much easier than trying to grapple with e.g. RPM packaging.

              "Binary tarballs, as you say, are limited/useless"

              I didnt say that at all. They are great!

        • by aitikin (909209)

          Sorry, but it *is* difficult to get from a compilable program to a distributable program that Linux users can try out easily.

          You suggest tarballs, meaning configure && make && make install. That means you need to deal with automake and friends which are insanely obscure and hard to learn.

          I thought those were inherent to Linux users. I have never had a Linux install going for longer than a month where I hadn't at least once dropped to command line to put in some variant of configure && make && make install and get a new program running...

          Guess this is my get off my lawn post...

    • by TheRaven64 (641858) on Wednesday September 11, 2013 @04:58AM (#44817359) Journal
      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.
  • by gmuslera (3436) on Tuesday September 10, 2013 @11:44PM (#44816281) Homepage Journal
    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 [docker.io] 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.
  • by Anonymous Coward

    GPL, LGPL, MIT, etc etc

    • Re: (Score:3, Interesting)

      by Anonymous Coward
      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).
  • 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 (Score:5, Insightful)

    by G3ckoG33k (647276) on Tuesday September 10, 2013 @11:54PM (#44816325)

    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.

    • by Anonymous Coward

      Also, consider planning for multi-arch as well. Both 32- and 64-bit intel, at least, in the source. Don't make people have to choose now, and then be stuck with it.

    • by Jezral (449476) <mail@tinodidriksen.com> on Wednesday September 11, 2013 @02:35AM (#44816943) Homepage

      I'd love to do that, but getting a package into Debian is a nightmare that I have simply given up on. Even the simple guides are 50 pages long and a mass of not quite up-to-date information.

      Ubuntu makes it trivial. Even if you can't or don't want to get into Ubuntu base, you can just make a PPA on Launchpad and get automatic building for all supported editions and archs of Ubuntu.

      • by Anonymous Coward

        Ubuntu now reject new packages and tell people to put packages into Debian, which isn't that hard now:

        http://mentors.debian.net/intro-maintainers

      • Getting a package into Debian is hard, but it's perfectly acceptable to release Debian packages standalone alongside your tarballs, or to host your own repository. The package format itself is pretty simple, and making them can be as easy as arranging your files, writing a few lines in a control file and running "dpkg-deb -b". I do this when I make changes to my system, since it makes them easy to undo.

        The 50 page guides are for Debian's own standards, which you must follow to get a package into Debian. If

    • by Arker (91948) on Wednesday September 11, 2013 @02:55AM (#44817005) Homepage
      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 (Score:4, Insightful)

    by Anonymous Coward on Wednesday September 11, 2013 @12:02AM (#44816365)

    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 can't agree more!

      1. There are some great open source programs out there -- unfortunately if I can't freaking compile _your_ code _I_ can't help verify that my patches actually work! Result? Not even going to waste my time trying to compile your crap.

      2. Give me a freakin SUMMARY of WHAT problem your open source program solves.

      3. Use a GOOD coding style with _descriptive_ variable names. Have a wiki or page that DESCRIBES the coding standard used by the project.

      4. List what LICENSE the code is. Is it GPL

  • by Anonymous Coward

    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 affe

    • 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:

      • Provide the tarballs
      • Provide a list of dependencies (don't make me run
  • by Anonymous Coward on Wednesday September 11, 2013 @12:12AM (#44816419)

    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.

  • by gentryx (759438) * on Wednesday September 11, 2013 @12:15AM (#44816435) Homepage Journal
    *wink*library for computer simulations [libgeodecomp.org] *wink*
    • I'm sorry to say that I've no use for what you've put together; I really wish I did, though. You made me chuckle at the end of a series of really long days. Thank you very much.
      • by gentryx (759438) *

        Thanks, I appreciate it!

        No worries though. I'm currently in the technology transfer phase of my PhD, meaning that the project has achieved most of its scientific goals and I'm now rolling it out to the users. We already have a couple of users and the project even gathered a certain momentum recently, so I'm fine. But attracting more obviously wouldn't hurt.

        • . . .transfer phase of my PhD. . .

          I That's farther than I guessed you were.

          . . .couple of users. . .

          You've astounded me further. My first guess after looking over your project was that you would be lucky to get any users at all. I'm not, by any possible stretch an expert in your field, so don't take my opinion with even a grain of salt. (I design safety improvements for roads in an arctic environment. It seems possible, though, that somebody might use your specialty to help with mine. I love convergence.)

          Good luck with your project, and thanks for the hearty

    • Very interesting. Do you use multigrid methods to solve the equations?

      • by gentryx (759438) *
        The library is really built with the mindset "one grid to rule them all". Also, it's not limited to solvers. But yeah, you definitely can use it to write multigrid solvers. It's a bit unorthodox though, so I guess anyone trying that should send me an email so I can explain the methodology. The basic idea is simple: 1. define the iteration scheme, 2. create multiple grids (or levels), 3. couple them (for interpolation), 4. run :-)
  • by Anonymous Coward

    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.

  • by 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

    • by Chemisor (97276)

      If the project will no longer compile with the lastest versions of the 85 dependencies, the precompiled binary will not run with the latest versions of the 85 dependencies. We ship the source code precisely so you can build it to match what you have installed.

  • by emblemparade (774653) on Wednesday September 11, 2013 @01:10AM (#44816639)

    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!

    • 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...
  • No (Score:3, Insightful)

    by drwho (4190) on Wednesday September 11, 2013 @01:23AM (#44816681) Homepage Journal

    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.

    • by rubycodez (864176)

      you're confused, all the major project started out as shit that was widely distributed then improved: Linux, gnu compiler collection, apache http server, sendmail...

      meanwhile, in the closed source world, same model followed. windows 1.0 sucked too

  • ...He didn't mention how to choose an appropriate software license!

    That's definitely something that impacts the popularity of any open-source project.

  • by tlambert (566799) on Wednesday September 11, 2013 @04:19AM (#44817219)

    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.

    • by Xyrus (755017)

      ...Otherwise, you are just navel gazing.

      There's an app for that.

    • by c0d3g33k (102699)

      Best /. post ever. Thanks.

  • 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
  • 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.

  • 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 t

  • 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

Maybe Computer Science should be in the College of Theology. -- R. S. Barton

Working...