This is a placeholder for an upcoming guide for upstream authors.

random thoughts

This list will contain things to check as an upstream author. At the time of writing this list is informal and just there to collect thoughts. It will be converted to a real page later on. Feel free to add anything you have to tell upstream authors or you have already learned as an upstream author.

• Always have a complete license with your package. Don't just refer, GPL states a copy should be given along with the code. Name that file COPYING and put it in the packages root directory.
• Make sure that licensing of each and every file is clear, and of course open. Closed licenses won't make it into universe.
• Packaging will require copyright notes, so make a packager's life easier by adding these information in a clearly stated file. Add all contributers, as well as translators, artworkers, etc.
• If your package includes a globally executable file it should have a man page. Your package should have documentation anyway but a missing man page is a no-go for debian package policies. Documentation is good!
• Don't release non script/binary files with the execution bit set
• Release the source as a tar.gz with the root folder been foo-1.2 for a source release download of foo-1.2.tar.gz

DRAFT.

Introduction

This page is intended as a guide for upstream authors who wish to cooperate with the packagers of Ubuntu Universe to create the best possible experience for the users, and to make the life of the packagers easier.

Ubuntu and Debian packages are subject to a number of requirements, that are defined in the [http://www.debian.org/doc/debian-policy/ Debian Policy Manual].

As an upstream author, you are free to be blissfully ignorant of this policy. But the packagers are not, so to help them, please consider the proposals outlined in this document, they are indeed quite simple and easy to implement

License & copyright

The license to distribute your software, and the copyrights that apply to it, is the first thing that is considered when a software package is introduced into the Universe.

First of all, it is necessary that that your software can be distributed with a license in agreement with the [http://www.debian.org/social_contract#guidelines Debian Free Software Guidelines] (DFSG). The [http://www.gnu.org/copyleft/gpl.html GPL], [http://www.debian.org/misc/bsd.license BSD], and [http://www.perl.com/pub/a/language/misc/Artistic.html “Artistic”] licenses are examples of licenses that we consider “free”.

The choice of license is entirely up to you, but we ask you to fulfill the following two points:

• Place a file containing the text of the license in a file called COPYING, LICENSE, gpl.txt, bsd.txt or something similar in the top directory of your software distribution.

• Place either the entire license, or an appropriate clause of it at the beginning of every single source file that is covered by the license. We need to be able to ascertain that we are allowed to distribute every single part of the code, including the documentation.

Another important point concerns the copyright. We cannot distribute anything that does not have a clear indication of who owns the copyright of the software. Thus, we need you to:

• Place a file, named AUTHORS, Copyright or something similar, in the top directory of your software distribution. In that file, please acknowledge all authors who have copyright to parts of your software, and for which years that copyright applies.

Name & version

You are of course free to choose any name for your software that you find appropriate! We are sure that you have thought long and hard to find a unique name that you and others like.

When generating a package containing your software, we are however bound by policy. First of all, all packages have all lower-case names, without spaces, and without underscores. If your software's name contain an underscore, we will have to replace that, often with a dash.

You are also free to choose any versioning scheme that you find suitable to your needs. However, some de-facto standards for versioning of free software have developed. Many software developers choose a scheme using numbers, e.g. {version}.{release}.{patch}. Others use a date base versioning scheme, e.g. 20080210.

Whatever versioning scheme you use, we ask you to choose one that has a sorting property that will list the newest versions last in a numerical sort. The two examples above both have that property, but version strings like 12Dec04 and 24Nov04 do not.

tarballs for download

To put it bluntly:

• please distribute your software in a gzipped tar archive.

If you do not, the packager will have to repackage your tarball, and that makes it more difficult to ensure that the package indeed contains a pristine tarball.

Most likely, like tens of thousands of software developers around the globe, you distribute your software from an ftp site or a homepage on the Internet.

We have an automatic system, that can check whether a package is up-to-date with the upstream distribution. The system looks up the site, tries to work out the version of the distributed tarball, and compares it to the version found in the package.

For this to work well, it is best if your tarball has a name that encodes the version, most typically something like:

• foobar-3.1.2.tar.gz

Building your software

• Makefiles
  • ⁃ GNU make is OK ⁃ provide a flexible build system that allows customised installation, ⁃ don't build stuff on clean, ⁃ don't download from the net, ⁃ etc.
• GNU autoconf
  • - rpath
• other build systems
  • - cmake - ant

Writing manfiles

In the Debian and Ubuntu distributions, every executable program must have a man page. In fact, it is considered a bug in the package, if such a manpage is missing.

One of the most frequently required tasks of packagers is to write the missing man pages. A man page is a simple, but important way to document the function of your software. You can help the maintainers a lot by supplying either a manpage (the luxury solution) or, a README file or something similar, that gives the relevant information for the packager to write the man pages.

Fortunately, there are several tools that can assist you. help2man is a simple system that attempts to generate a man page by running the program with the --help and --version switches.

Another program that can help you -- if you don't want to bother with learning nroff markup -- is the asciidoc program, that can convert consistently formatted text files to nroff format, or even html.

Special cases

• Java programs
• Python programs
• Python modules
• Perl

Patches from package maintainers

One advantage that you have as a software developer is that you can benefit from Ubuntu's extensive Bug Tracking System, called [http://launchpad.net Launchpad]. Any user using your software can report bugs or misbehaviors they find on that system. A bug in a given package will normally trigger an email to the package maintainer, who will either issue a fix, or perhaps forward a request to you.

Some maintainers are eloquent programmers, and if they are able to fix a bug in your software, they will often forward a patch to you. Indeed, we encourage the Ubuntu Universe maintainers to contribute patches upstream.

Case stories

Examples of packagers' difficulties

["CategoryMOTU"]