Morten Kjeldgaard has proposed merging lp:~mok0/ubuntu-packaging-guide/upstream-guide into lp:ubuntu-packaging-guide.
Requested reviews: Ubuntu Packaging Guide Team (ubuntu-packaging-guide-team) For more details, see: https://code.launchpad.net/~mok0/ubuntu-packaging-guide/upstream-guide/+merge/53166 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! -- https://code.launchpad.net/~mok0/ubuntu-packaging-guide/upstream-guide/+merge/53166 Your team Ubuntu Packaging Guide Team is requested to review the proposed merge of lp:~mok0/ubuntu-packaging-guide/upstream-guide into lp:ubuntu-packaging-guide.
=== 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
_______________________________________________ Mailing list: https://launchpad.net/~ubuntu-packaging-guide-team Post to : [email protected] Unsubscribe : https://launchpad.net/~ubuntu-packaging-guide-team More help : https://help.launchpad.net/ListHelp
