Dos and Don'ts

This list will contain things to check as an upstream author. Feel free to add anything you have to tell upstream authors or you have already learned as an upstream author. Think of it as a growing checklist of things to do and not to do to make Ubuntu integration of your package easier or even possible at all.

• Always have a complete license with your package. Don't just refer, full license preferably called 'COPYING' in the packages root directory. why?

• Make sure that licensing of each and every file is clear, and of course open. Closed licenses won't make it into universe. why?

• Maintain a changelog file with notes on updates and bug-fixes why?

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

• If your package includes a globally executable file it should have a man page. No man page, no Ubuntu package. why?

• 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 why?

• Be sure to give a compatible versioning scheme like 1.2.5 why?

• If compiling takes place (as in C, C++ projects) make use of GNU's make system. why?

This list is of course not complete but should help you getting out of the usual trouble.

---

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 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 Debian Free Software Guidelines (DFSG). The GPL, BSD, and “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

When preparing your tarball, the packager of your software will prefer that you:

• do not ship compiled files
• do not ship pdf files or other "compiled" text formats. We distribute "preferred modifiable format" files only

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

Maintain a changelog file

It is a great help to both users and packagers if you maintain a changelog file in the top directory of your package. This will help the packager decide:

• what novel and exciting features are in the new release?
• is it a bug-fix release? How severe is the bug?
• with what urgency should the new version be pushed to the distribution?
• Is it worthwhile seeking a "Stable Release Update"?

Your changelog becomes a part of the package's documentation and will reside in the /usr/share/doc tree.

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