UpstreamGuide

Differences between revisions 8 and 9
Revision 8 as of 2008-02-18 13:37:01
Size: 8579
Editor: fw1
Comment: Add section on maintaining changelog files
Revision 9 as of 2008-05-09 16:59:05
Size: 8811
Editor: 563413c5
Comment: Added comments about what NOT to ship
Deletions are marked like this. Additions are marked like this.
Line 72: Line 72:
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

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. [#license why?]
  • Make sure that licensing of each and every file is clear, and of course open. Closed licenses won't make it into universe. [#license why?]
  • Maintain a changelog file with notes on updates and bug-fixes [#changelog 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. [#license why?]
  • If your package includes a globally executable file it should have a man page. No man page, no Ubuntu package. [#man 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 [#tarball why?]
  • Be sure to give a compatible versioning scheme like 1.2.5 [#version why?]
  • If comiling takes place (as in C, C++ projects) make use of GNU's make system. [#make why?]

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


DRAFT.

Anchor(intro)

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

Anchor(license)

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.

Anchor(name)

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.

Anchor(tarball)

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

Anchor(building)

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

Anchor(changelog)

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.

Anchor(man)

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

Anchor(patches)

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

UpstreamGuide (last edited 2008-10-01 03:52:02 by cpe-76-187-176-203)