Some Tips for Software Publishing

[Deque]

You wrote a tool that you want to make public, so others can and will use it?
Here are some general advices for you.


General

Make it Easy to Submit Bug Reports

This includes:

* Provide contact information and a common site to submit bugs. E.g. if you use GitHub to host your project, bugs can be submitted there.
* You may let your program take care of sending bug reports to you, if it crashes
* Use a good logging mechanism and well written error messages so you can track the cause of the bug. Logging libraries create log files for you which might be sent to you in case of a bug.
* Never swallow exceptions or errors. E.g. never do this:

Code: [Select]

try {
 //try something that might fail
} catch (Exception e) {
 // do nothing if it fails
}

Provide Documentation

Documentation is very important. It explains the user how to use your software. The documentation can include:

* Readme
* Code documentation (HTML docs, code comments)
* Manual
* Wiki
* Project website
* Contact information
* Usage examples

The first two are most important for open-source projects.

Installation Should be a Breeze

Use setup files or installers. The user should not do more steps than necessary to install and use your software. Even if the steps seem easy to you, if you can do it in a script or installation wizard instead, do it.

For linux software you might provide actual distribution packages, e.g., .deb files.

Don't Underestimate the Value of a Good User Interface

The user interface is all the user can see. He or she will judge the program more by the interface than your beautiful code or efficient algorithm.
A good user interface is:

* easy-to-use, not many clicks needed, self-explanatory
* a CLI interface should provide usage by command line arguments, this is usually more convenient than interactive interface, you need to know your target audience, though. *nix users will prefer command line arguments. Windows users usually don't like CLI programs at all.
* provides always proper feedback: Use progress bars if a process takes longer than 2 seconds, otherwise the user might think the program does not work. Provide proper messages if the user does something wrong. Always assume that the user will do something wrong.
* nice-looking (yes, that's how the mind works)


Open Source Tools

For open source projects there are three very important things: Your source must be made publicly availble (otherwise it is not open source), your project should allow others to contribute easily (bug reporting, bug fixes, forks, etc), and you need a license to tell others what they can and cannot do with your code.

Publish the Source on a Repository Hosting Service.

These hosting services are usually tied to a software versioning and revision control system. Examples are: Git, SVN, Mercurial.
You need to know how to use them in order to use the hosting services for your code. SVN is probably the most easiest to start with, however, Git is more modern and flexible.

Repository Hosting Services:

SourceForge: (CVS, SVN, Bazaar, Git, Mercurial)
http://sourceforge.net/
Provides: project wikis, metrics and analysis, access to a MySQL database, and unique sub-domain URLs.

GitHub: (Git)
https://github.com/
Provides: Wikis, task management, bug tracking, feature requests, small project websites. Only public repos are free.
GitHub is the largest repository hoster in the world.

Bitbucket: (Git, Mercurial)
https://bitbucket.org
Provides: Among others, unlimited number of private repositories. The number of users who can join private repos is restricted.

Google Developers: (SVN, Mercurial, Git)
https://code.google.com/hosting/
Provides: An issue tracker, a wiki for documentation, 25 projects max (which is not much), 200MB default upload file size limit (can be upgraded to 5 GB)

Provide a LICENSE

An open-source project without a license is worth nothing. You have to tell people somehow what they are allowed to do with your code.
There are lots of licenses you can choose from and hosting services like GitHub will generate the file for you.
But you need to know what license suits your needs. I will explain some examples briefly.

BSD Licenses:
Developers like the BSD Licenses, because they are very simple. They have two to four clauses only. You can actually read and understand the license within a few minutes. See here for more: http://en.wikipedia.org/wiki/BSD_license
However, this has drawbacks. There are reasons for licenses to be huge, they cover things which are unexplained here. I think BSD Licenses are ok for small and simple projects, but if you have a project that is really important to you, you should consider taking another license.


GNU General Public License (GPL):
The open-source license. I think the most critical part is the copyleft. Distribution and changes to your code are only allowed if the same license is used again. This is very restrictive in my opinion and only fits if you agree with the philosophy of Stallman.


Apache License:
My personal favourite for larger projects. It requires preservation of the copyright notice and disclaimer, allows distribution, modification and distribution of modified versions of the software, under the terms of the license, without concern for royalties.

Building Your Project Must be Easy

Make it easy for people to build your project. This includes:

* proper documentation, build instructions (as already covered)
* configuration files for project management or build tools, examples are: Maven for Java, SBT for Scala, pip and setup.py for Python
These build tools take care for any dependencies of your project. Don't let the others figure out how to compile your code. The build tool you use depends on the language implementation of your project.
* if necessary register your program at the web services that are used by these build tools, e.g. SBT and Maven: http://search.maven.org/, pip for Python https://pypi.python.org/pypi

[Spacecow]

Very nicely formatted and informative post, I think it would be worth it to expand it a little further and sticky it.

[Schalla]

Well done Deque, take a cookie!

[Xires]

I agree; well done.  Definitely deserving of a few cookies.