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

Proposed by Morten Kjeldgaard
Status: Work in progress
Proposed branch: lp:~mok0/ubuntu-packaging-guide/upstream-guide
Merge into: lp:ubuntu-packaging-guide
Diff against target: 266 lines (+262/-0)
1 file modified
upstream-guide.rst (+262/-0)
To merge this branch: bzr merge lp:~mok0/ubuntu-packaging-guide/upstream-guide
Reviewer Review Type Date Requested Status
Daniel Holbach Needs Fixing
Review via email: mp+53166@code.launchpad.net

Description of the change

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!

To post a comment you must log in.
Revision history for this message
Daniel Holbach (dholbach) wrote :

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

Merge from trunk

22. By Morten Kjeldgaard

Upstream guide now in rSt format

21. By Morten Kjeldgaard

upstream-guide: raw text from wiki

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== added file 'upstream-guide.rst'
2--- upstream-guide.rst 1970-01-01 00:00:00 +0000
3+++ upstream-guide.rst 2011-03-13 10:38:03 +0000
4@@ -0,0 +1,262 @@
5+.. This text is from https://wiki.ubuntu.com/UpstreamGuide
6+.. delete from Wiki when done.
7+
8+.. External URLs defined here:
9+.. _Launchpad: http://launchpad.net|Launchpad
10+
11+
12+Guide for Upstream Authors
13+==========================
14+
15+
16+
17+
18+Introduction
19+------------
20+
21+This page is intended as a guide for upstream authors who wish to
22+cooperate with the packagers of Ubuntu Universe to create the best
23+possible experience for the users, and to make the life of the
24+packagers easier.
25+
26+Ubuntu and Debian packages are subject to a number of requirements,
27+that are defined in the
28+`Debian Policy Manual <http://www.debian.org/doc/debian-policy/>`_
29+
30+As an upstream author, you are free to be blissfully ignorant of this
31+policy. But the packagers are not, so to help them, please consider
32+the proposals outlined in this document, they are indeed quite simple
33+and easy to implement
34+
35+What is a package?
36+-----------------
37+
38+TBD.
39+
40+
41+License & copyright
42+-------------------
43+
44+The license to distribute your software, and the copyrights that apply
45+to it, is the first thing that is considered when a software package
46+is introduced into the Universe.
47+
48+First of all, it is necessary that that your software can be
49+distributed with a license in agreement with the `Debian Free Software
50+Guidlines <http://www.debian.org/social_contract#guidelines>`_
51+(DFSG). The `GPL <http://www.gnu.org/copyleft/gpl.html>`_, `BSD
52+<http://www.debian.org/misc/bsd.license>`_, and `"Artistic"
53+<http://www.perl.com/pub/a/language/misc/Artistic.html>`_ licenses are
54+examples of licenses that we consider "free".
55+
56+The choice of license is entirely up to you, but we ask you to fulfill
57+the following two points:
58+
59+ * Place a file containing the text of the license in a file called
60+ ``COPYING``, ``LICENSE``, ``gpl.txt``, ``bsd.txt`` or something
61+ similar in the top directory of your software distribution.
62+ * Place either the entire license, or an appropriate clause of it
63+ **at the beginning of every single source file** that is covered by
64+ the license. We need to be able to ascertain that we are allowed to
65+ distribute every single part of the code, **including the
66+ documentation**.
67+
68+Another important point concerns the copyright. We cannot distribute
69+anything that does not have a clear indication of who owns the
70+copyright of the software. Thus, we need you to:
71+
72+ * Place a file, named ``AUTHORS``, ``Copyright`` or something
73+ similar, in the top directory of your software distribution. In
74+ that file, please acknowledge all authors who have copyright to
75+ parts of your software, and for which years that copyright applies.
76+
77+Name & version
78+--------------
79+
80+You are of course free to choose any name for your software that you
81+find appropriate! We are sure that you have thought long and hard to
82+find a unique name that you and others like.
83+
84+When generating a package containing your software, we are however
85+bound by policy. First of all, all packages have all lower-case names,
86+without spaces, and without underscores. If your software's name
87+contain an underscore, we will have to replace that, often with a
88+dash.
89+
90+You are also free to choose any versioning scheme that you find
91+suitable to your needs. However, some de-facto standards for
92+versioning of free software have developed. Many software developers
93+choose a scheme using numbers, e.g. ''{version}.{release}.{patch}''.
94+Others use a ISO date based versioning scheme, e.g. 20110313.
95+
96+Whatever versioning scheme you use, we ask you to choose one that has
97+a sorting property that will list the newest versions last in a
98+numerical sort. The two examples above both have that property, but
99+version strings like 12Dec04 and 24Nov04 do not.
100+
101+.. _tarballs:
102+
103+tarballs for download
104+---------------------
105+
106+The most important part of a Debian format source package is the
107+pristine upstream source tarball. The current source package format
108+supports three different archive formats: ``tar.gz``, ``tar.bz2``and
109+``.tar.lzma``. So, please distribute your software in a gzipped tar
110+archive. If you do not, the packager will have to repackage your
111+tarball, and that makes it more difficult to ensure that the package
112+indeed contains a pristine tarball.
113+
114+Most likely, like tens of thousands of software developers around the
115+globe, you distribute your software from an ftp site or a homepage on
116+the Internet.
117+
118+We have an automatic system, that can check whether a package is
119+up-to-date with the upstream distribution. The system looks up the
120+site, tries to work out the version of the distributed tarball, and
121+compares it to the version found in the package.
122+
123+For this to work well, it is best if your tarball has a name that
124+encodes the version, most typically something like:
125+
126+ foobar-3.1.2.tar.gz
127+
128+When preparing your tarball, the packager of your software will prefer
129+that you:
130+
131+ * do not ship compiled files
132+ * do not ship pdf files or other "compiled" text formats. We
133+ distribute "preferred modifiable format" files only
134+
135+.. _building:
136+
137+Building your software
138+----------------------
139+
140+TBD
141+
142+ * Makefiles
143+ * GNU make is OK
144+ * provide a flexible build system that allows customised installation,
145+ * don't build stuff on clean,
146+ * don't download from the net,
147+ * etc.
148+
149+ * GNU autoconf
150+ * rpath
151+
152+ * other build systems
153+ * cmake
154+ * ant
155+
156+.. _changelog:
157+
158+Maintain a changelog file
159+-------------------------
160+
161+It is a great help to both users and packagers if you maintain a
162+changelog file in the top directory of your package. This will help
163+the packager decide:
164+
165+ * what novel and exciting features are in the new release?
166+ * is it a bug-fix release? How severe is the bug?
167+ * with what urgency should the new version be pushed to the distribution?
168+ * Is it worthwhile seeking a "Stable Release Update"?
169+
170+Your changelog becomes a part of the package's documentation and will
171+reside in the ``/usr/share/doc`` tree.
172+
173+
174+Writing man pages
175+-----------------
176+
177+In the Debian and Ubuntu distributions, every executable program must
178+have a man page. In fact, it is considered a bug in the package, if
179+such a manpage is missing.
180+
181+One of the most frequently required tasks of packagers is to write the
182+missing man pages. A man page is a simple, but important way to
183+document the function of your software. You can help the maintainers a
184+lot by supplying either a manpage (the luxury solution) or, a README
185+file or something similar, that gives the relevant information for the
186+packager to write the man pages.
187+
188+Fortunately, there are several tools that can assist you. ``help2man``
189+is a simple system that attempts to generate a man page by running the
190+program with the ``--help`` and ``--version`` switches.
191+
192+Another program that can help you -- if you don't want to bother with
193+learning nroff markup -- is the asciidoc program, that can convert
194+consistently formatted text files to nroff format, or even html.
195+
196+
197+Special cases
198+-------------
199+
200+TBD
201+
202+ * Java programs
203+ * Python programs
204+ * Python modules
205+ * Perl
206+
207+
208+Patches from package maintainers
209+--------------------------------
210+
211+One advantage that you have as a software developer is that you can
212+benefit from Ubuntu's extensive Bug Tracking System, called
213+Launchpad_. Any user using your software can report bugs or
214+misbehaviors they find on that system. A bug in a given package will
215+normally trigger an email to the package maintainer, who will either
216+issue a fix, or perhaps forward a request to you.
217+
218+Some maintainers are eloquent programmers, and if they are able to fix
219+a bug in your software, they will often forward a patch to
220+you. Indeed, we encourage the Ubuntu Universe maintainers to
221+contribute patches upstream.
222+
223+
224+
225+Case stories
226+------------
227+
228+TBD
229+
230+Examples of packagers' difficulties
231+
232+
233+
234+Dos and Don'ts
235+--------------
236+
237+This list will contain things to check as an upstream author. Feel
238+free to add anything you have to tell upstream authors or you have
239+already learned as an upstream author. Think of it as a growing
240+checklist of things to do and not to do to make Ubuntu integration of
241+your package easier or even possible at all.
242+
243+ * Always have a co mplete license with your package. Don't just
244+ refer, full license preferably called 'COPYING' in the packages
245+ root directory.
246+ * Make sure that licensing of each and every file is clear, and of
247+ course open. Closed licenses won't make it into universe.
248+ * Maintain a changelog file with notes on updates and bug-fixes
249+ * Packaging will require copyright notes, so make a packager's life
250+ easier by adding these information in a clearly stated file. Add
251+ all contributers, as well as translators, artworkers,
252+ etc.
253+ * If your package includes a globally executable file it should have
254+ a man page. No man page, no Ubuntu package. The packager can often
255+ help you write the man-page.
256+ * Don't release non script/binary files with the execution bit set
257+ * Release the source as a tar.gz with the root folder been foo-1.2
258+ for a source release download of foo-1.2.tar.gz
259+ * Be sure to give a compatible versioning scheme like 1.2.5
260+ * If compiling takes place (as in C, C++ projects) make use of GNU's
261+ make system.
262+
263+This list is of course not complete but should help you getting out of
264+the usual trouble.
265+
266+.. end-of-file

Subscribers

People subscribed via source and target branches