Merge lp:~mok0/ubuntu-packaging-guide/upstream-guide into lp:ubuntu-packaging-guide

[Morten Kjeldgaard]

I have rStified the Upstream Guide from the Wiki that I initiated several years ago, but it was never finished and although a few people contributed, I ran out of steam. However, I still think the idea of having a "guide for upstreams" is a good one, it is a document packagers could point to in their collaboration with software developers. I would very much appreciate your input!

[Daniel Holbach (dholbach)]

The guide generally looks good to me! Good work! Maybe once it's landed we can file bugs for all the "XXX" sections in there?

A few small notes:

 - second sentence needs a "." at the end
 - bullet points in "Building your software" are mis-formatted
 - "*.tar..." mis-formatted
 - link to "stable release update" documentation

Thanks for your work on this.

review: Needs Fixing

Unmerged revisions

23. By Morten Kjeldgaard on 2011-03-13

Merge from trunk

22. By Morten Kjeldgaard on 2011-03-13

Upstream guide now in rSt format

21. By Morten Kjeldgaard on 2011-02-18

upstream-guide: raw text from wiki

=== added file 'upstream-guide.rst'
--- upstream-guide.rst	1970-01-01 00:00:00 +0000
+++ upstream-guide.rst	2011-03-13 10:38:03 +0000
@@ -0,0 +1,262 @@
+.. This text is from https://wiki.ubuntu.com/UpstreamGuide	
+.. delete from Wiki when done.
+
+.. External URLs defined here:
+.. _Launchpad: http://launchpad.net|Launchpad
+
+
+Guide for Upstream Authors
+==========================
+
+
+
+
+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 <http://www.debian.org/doc/debian-policy/>`_
+
+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
+
+What is a package?
+-----------------
+
+TBD.
+
+
+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
+Guidlines <http://www.debian.org/social_contract#guidelines>`_
+(DFSG). The `GPL <http://www.gnu.org/copyleft/gpl.html>`_, `BSD
+<http://www.debian.org/misc/bsd.license>`_, and `"Artistic"
+<http://www.perl.com/pub/a/language/misc/Artistic.html>`_ 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 ISO date based versioning scheme, e.g. 20110313.
+
+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:
+
+tarballs for download
+---------------------
+
+The most important part of a Debian format source package is the
+pristine upstream source tarball.  The current source package format
+supports three different archive formats: ``tar.gz``, ``tar.bz2``and
+``.tar.lzma``. So, 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:
+
+Building your software
+----------------------
+
+TBD
+
+ * 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
+
+.. _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.
+
+
+Writing man pages
+-----------------
+
+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
+-------------
+
+TBD
+
+ * 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
+------------
+
+TBD
+
+Examples of packagers' difficulties
+
+
+
+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 co mplete license with your package. Don't just
+   refer, full license preferably called 'COPYING' 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.
+ * Maintain a changelog file with notes on updates and bug-fixes
+ * 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. No man page, no Ubuntu package. The packager can often
+   help you write the man-page.
+ * 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 
+ * Be sure to give a compatible versioning scheme like 1.2.5
+ * If compiling takes place (as in C, C++ projects) make use of GNU's
+   make system.
+
+This list is of course not complete but should help you getting out of
+the usual trouble.
+
+.. end-of-file