DEBIAN POLICY WEEKLY, #4 (October 23, 1997)
DEBIAN POLICY WEEKLY, #4 (October 23, 1997)
The following message is a list of topics related to the Debian Policy which
are currently under discussion or which will be discussed in the near
future. This summary is sent to the debian-policy mailing list periodically
by the Debian Policy Manager.
A copy of this mail is sent to debian-devel to keep other developers
up-to-date. Please send any replies to the debian-policy mailing list.
Please do not quote the whole mail if you are only referring to a single
section to save bandwidth.
----------------------------------------------------------------------------
The Policy Manual on the Web
This message can also be read online at
http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-policy/weekly/
The Home Page of the Debian Policy Manual can be visited at
http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-policy/
This page contains links to the current documents, information about the
current development version (2.3.1.0 DRAFT), and links to related documents.
----------------------------------------------------------------------------
Policy changes that need to be approved
The following policy changes have been developed during recent discussion on
the mailing lists. If there are no objections, these changes will become
`official policy'.
The changes have already been worked into the current draft version of the
policy manual. (You might want to check out the draft if you want to see how
the changes integrate into the manual.)
1. Bash vs Bourne shell
2. Serial devices
3. Guidelines for Motif applications
4. Announcing new packages before uploading them
5. Shared configuration files for news servers
6. Secure maintainer scripts
7. Leaving time stamps unmodified
8. Dates in package versions
Policy topics about which I need additional input
The following topics have been discussed on the mailing lists or in private
mail. I need more information and personal opinions about these topics to
prepare a policy change:
9. Usage of `must' and `should' in the manual
10. Filesystem location of non-english documentation files
11. UUCP-locking of devices
12. X Window Manager policy
Policy topics which need to be discussed
The following ideas have been mentioned in recent discussions. Any input is
appreciated.
13. Starting daemons in the postinst scripts
14. Manual page inconsistencies
Postponed policy discussions
The following topics showed up in the past and have been postponed. There
are mentioned here to inform intrested developers that these topics have not
been forgotten. However, there is no need to raise any of these discussions
again. This will be done by the Policy Manager when its time for it. (You
can send him a private email if you think the discussion should be
continued.)
15. Documentation policy
16. New source package format
----------------------------------------------------------------------------
Topic 1: Bash vs Bourne shell
STATE: APPROVAL
There has been a long discussion on debian-policy about which features may
be used from the default shell /bin/sh. Currently, several packages use
bash-specific features but specify "#!/bin/sh" as interpreter.
As some users want to use "ash" as "/bin/sh" to save disk and RAM space, all
scripts using "/bin/sh" may only use a common subset of some shells.
I present the following policy change for approval. If noone objects, this
will become official policy:
``The shell `/bin/sh' may be symbolic link to any POSIX compatible
shell. If a script uses non-POSIX features the appropriate shell
has to be specified in the first line of the script (i.e.
`#!/bin/bash') and the package has to depend on the package
providing the shell (unless the shell package is marked
`Essential').''
----------------------------------------------------------------------------
Topic 2: Serial devices
STATE: APPROVAL
The following policy has been suggested and will become official unless
someone objects: (the rationale will probably be removed since it's too long
for the policy manual)
Serial Devices
====== =======
Debian uses the new standard of /dev/ttyS? devices for serial
ports. No package shall use the older /dev/cu* devices.
Rationale:
---------
This is a quote from Theodore Ts'o , who implemented
these devices in the first place:
/dev/ttySxx devices are fully POSIX-compliant TTY devices. If you
are only going to be using one set of tty devices, you should be
using /dev/ttySxx.
/dev/cuaXX devices are different from /dev/ttySXX in two ways ---
first of all, they will allow you to open the device even if
CLOCAL is not set and the O_NONBLOCK flag was not given to the
open device. This allows programs that don't use the
POSIX-mondated interface for opening /dev/ttySxx devices to be
able to use /dev/cuaXX to make outgoing phone calls on their
modem (cu stands for "callout", and is taken from SunOS).
The second way in which /dev/cuaXX differs from /dev/ttySXX is
that if they are used, they will trigger a simplistic
kernel-based locking scheme: If /dev/ttySXX is opened by one or
more processes, then an attempt to open /dev/cuaXX will return
EAGAIN. If /dev/cuaXX is opened by one or more processes, then
an attempt to open /dev/ttySXX will result the open blocking
until /dev/cuaXX is closed, and the carrier detect line goes
high.
While this will allow for simple lockouts between a user using a
modem for callout and a getty listening on the line for logins,
it doesn't work if you need to arbitrate between multiple
programs wanting to do dialout --- for example, users wanting to
do dialout and UUCP.
I originally implemented the cuaXX/ttySXX lockout mechanism back
before FSSTND established a standard convention for the use of
tty lock files. Now that it's there, people should use the tty
lock files and not try using /dev/cuaXX. The only reason why
/dev/cuaXX hasn't disappeared yet is for backwards compatibility
reasons.
-- Theodore Ts'o
----------------------------------------------------------------------------
Topic 3: Guidelines for Motif applications
STATE: APPROVAL
The following policy has been suggested on debian-policy and will become
official unless someone objects:
Guidelines for Motif applications
---------------------------------
If you package a program that requires a non-free Motif library, it
would be good if you can provide a "foo-smotif" and a "foo-dmotif"
package, containing a (against Motif libraries) statically and a
dynamically linked version, respectively. This way, users without
Motif can use the package too, while users that have Motif installed
get the advantages of a dynamically linked verison.
Note, that packages that require non-free Motif libraries can't go
into the main distribution.
----------------------------------------------------------------------------
Topic 4: Announcing new packages before uploading them
STATE: APPROVAL
According to current policy, every upload of a new package to the archive
has to be announced on debian-devel _before_ the package is uploaded to the
master site. However, must developers do not know this yet. That's why it
should be documented. (I think the right place for this is the Debian
Developer's Reference.)
Here is a list of advantages of this policy:
* It helps the (potentially new) maintainer to tap into the experience of
people on the list, and lets them know if any one else is working on it
already
* It lets other people thinking about working on the package know that
there already is a volunteer, and efforts may be shared
* It lets the rest of the maintainers know more about the package than
the one line description and the changelog entry "Initial version" that
generally gets posted to debian-devel-changes by default
* It is helpful to the people who live off unstable (and form our first
line of testers); we should encourage these people
* I think the annoncements gives us a better feel of what is going on,
and what is new, in the project.
* We should not dismiss anybody who installs from usntable and helps us
debug our packages as "fools, fools, you installed from unstable; you
deserve what you get" -- we derive a certain benefit from the alpha
testers
* If we appreciate alpha testers, than any name changes have to be
backwards compatible with the people who already installed the old
package (conflict and relace old package name at a minimum)
----------------------------------------------------------------------------
Topic 5: Shared configuration files for news servers
STATE: APPROVAL
The following policy has been suggested on debian-policy and will become
official unless someone objects:
News system configuration
-------------------------
All the configuration files related to the NNTP (news) servers and
clients should be located under /etc/news. If any package has a
large number of configuration files, (like, for example, inn does),
then a package specific subdirectory under /etc/news should be used
(example: /etc/news/suck or /etc/news/inn). If only one or two files
are required, you may use a single file (example: /etc/news/mnews.conf).
There are some configuration issues that apply to a number of
news cliens and server packages on the machine, and these
configuration values should be kept directly under /etc/news;
specifically,
/etc/news/organization: A string wich shall appear as the
organization header for all messages posted
by NNTP clients on the machine
/etc/news/server: Contains the FQDN of the upstream NNTP
server, or localhost if the local machine is
an NNTP server.
Other global files may be added as required for cross-package news
configuration.
----------------------------------------------------------------------------
Topic 6: Secure maintainer scripts
STATE: APPROVAL
The following policy change has been proposed. It will become official
unless someone objects now:
Any scripts which create files in world-writable directories (i.e.
in /tmp) have to use a mechanism which will fail if a file with
the same name already exists.
The Debian base distribution provides the `tempfile' utility for
use by scripts for this purpose.
----------------------------------------------------------------------------
Topic 7: Leaving time stamps unmodified
STATE: APPROVAL
Most of our packages `touch' files in the packaging process (that is, the
modification time of the files gets reset to the current time). It would be
nice if the modification time of the upstream source would be preserved.
For example, you could recognize that some documentation is very old by
looking at the modification time. (Of course, this only works if the
upstream maintainer kept the original modification time.)
According to a recent discussion on debian-policy on this subject we
consider this topic as `nice-to-have', but without priority. Maintainers are
encouraged to keep the original time stamps, though.
I suggest that an appropriate note is added to the Packaging Manual.
----------------------------------------------------------------------------
Topic 8: Dates in package versions
STATE: APPROVAL
Some upstream sources use a `snapshot date' instead of a real version
number. As these `dates' are used as version id for dpkg it is useful to
make them all use the same format. (It doesn't matter if our version number
_looks_ different than the one from the upstream source when a date is used.
For example, everyone should be able to recognize that `96May05' is the same
as `1996.05.05'.)
Note, that our intention is not to make the upstream maintainer change
his/her version numbers. We only try to get unique version numbers within
our distribution.
I suggest that the following text will be added to the Debian Packaging
Manual.
When choosing a version number for the .orig source, you should first try
to respect the original version number if possible.
If you are unable to determine the version number, you may use the date in
which the program was written. When using a date as version number, use
always the YYYY.MM.DD format (i.e. 4 digits for the year, 2 for the month
and 2 for the day).
If you are quite sure that upstream releases are monthly (e.g. for
e-magazines), you can use also the short form: YYYY.MM
----------------------------------------------------------------------------
Topic 9: Usage of `must' and `should' in the manual
STATE: INPUT
Some people said that we should (or must? :-) change `should' into `must' in
the Policy Manual in most places, even if exceptions are allowed, since the
RFC's use this wording and some people might get confused, otherwise. Any
objections?
----------------------------------------------------------------------------
Topic 10: Filesystem location of non-english documentation files
STATE: INPUT
Background
There was a discussion about this topic on debian-devel around Nov 96, but
without any decision. Since a lot of package already install non-english
docs, we'll have to find a solution soon.
The previous discussion on this topic made clear, that we still have two
groups of people, one that prefers having the files in
/usr/doc/LANG/<locale> and symlinks in /usr/doc/<pkg>, and one that prefers
having the files in /usr/doc/<pkg>/<locale>.
In the past, the policy about doc files has been changed: We used to split
up the doc files into different directories (/usr/doc/copyright,
/usr/doc/examples, /usr/doc/<pkg>, etc.). Now we place all package-related
documentation files below /usr/doc/<pkg>.
Policy suggestion
In continuation of this policy I suggest to keep all documentation files in
one place: /usr/doc/<pkg>. In case of non-english docs, the files would be
placed into a subdirectory /usr/doc/<pkg>/LANG_<locale>
The locale string can have the form <language> or <language>_<territory>. It
is the maintainers job to decide which form to be used for a specific
documentation file.
The LANG_ prefix is used to reduce the possibility of a file name conflict.
(I don't think an extra LANG/ directory is appropriate here.)
Any program/script that needs to access documentation files mechanically
should search for the files in the following directories (in exactly this
order):
/usr/doc/<pkg>/LANG_<language>_<territory>/
/usr/doc/<pkg>/LANG_<language>/
/usr/doc/<pkg>/
Some people suggested to have an extra directory level for the documentation
file format (e.g. 'HTML/'). I suggest to postpone the discussion about this
sub-topic until we discuss the `documentation policy'. (Until then,
maintainers can decide whether they want to use an extra directory, or not.)
Feedback
Please tell me what you think about this suggestion. If people agree with my
proposal, I'll prepare the necessary policy changes and present them here
for approval.
----------------------------------------------------------------------------
Topic 11: UUCP-locking of devices
STATE: INPUT
REF: cf. bug #11094 and #10575
The FSSTND (as well as the FHS draft) specifies how programs have to lock
UUCP devices. Unfortunately, the locking mechanism has several flaws.
To solve this dilemma, Fabrizio Polacco built a library for device locking
(liblockdev) which is fully compliant to the FSSTND requirements but also
solves some problems of the locking mechanism.
I suggest to change policy so that every Debian package has to use
liblockdev to lock/unlock devices.
Any comments are appreciated.
----------------------------------------------------------------------------
Topic 12: X Window Manager policy
STATE: INPUT
Joey Hess wrote on Mon, 30 Jun 1997 to debian-devel:
I maintain KDE, which includes a window manager, and I've been wondering how
other window managers handle registering themselves in
/etc/X11/window-managers. So I took a look at all th window managers.
Some window managers add themselves to the top of the file, so they become the
default window manager. Others add themselves to the bottom of the file, so
the sysadmin doesn't get a chance to use them as a default window manager
without editing the file. And many window managers don't add themselves to the
file at all.
Here's a survey I did:
window manager adds itself to /etc/X11/window-managers how
-------------- -------------------------------------------
kde adds to bottom
afterstep adds to bottom
fvwm doesn't do so
fvwm2 doesn't seem to do so (complex postinst, I just grepped it
:-)
fvwm95 adds to top
gwm doesn't do so
9wm doesn't do so
ctwm doesn't do so
wm2 doesn't do so
wmaker doesn't do so
olvwm if olvwm entry not already present, prompt to make
default window manager or not, insert line in appropriate
place.
I think olvwm's behavior is the best of the lot, since it gives the sysadmin
a choice (and only asks once, not during upgrades, which is also very good
behavior). I wonder if it'd be a good idea for one of the X packages to
include a register-window-manager script that could be called from the
postinst's to handle this, so all window managers functioned exactly alike?
Linh Dang suggested:
Why not make /etc/X11/window-managers a directory which contains scripts for
windows managers. Change /etc/X11/Xsession to start
/etc/X11/window-managers/default (which is a symlink). A fvwm script should
looks like:
#!/bin/sh
exec fvwm -F /etc/X11/fvwm/system.fvwmrc
I'd prefer Joey's solution: xbase should install a script `install-wm' (or
similar) which is called by all window manager's postinst scripts. The
`install-wm' script will ask the sysadmin where to place the new wm (top or
bottom of the file).
Any other ideas?
----------------------------------------------------------------------------
Topic 13: Starting daemons in the postinst scripts
STATE: DISCUSSION
The following policy has been suggested:
If a package installs a `daemon' that is usually started via an
/etc/init.d/ script, the package should query the system
administrator after the installation (in the postinst script) if
he/she wants to start the daemon now.
(Does someone know a better wording for this?)
Question: Should this policy apply to all packages that install daemons or
only to packages which install a daemon as well as user/admin commands?
Wouldn't it be good if every script in /etc/init.d would start with a shell
variable that's set to 0 or 1, depending on whether the daemon should be
started at boot up time or not? For example:
#!/bin/sh
run_foo=0
test $run_foo == 0 && exit 0
...
The script (the variable) can be adapted by the postinst script. If the
sysadmin wants the start the daemon, it should be started in the postinst
script, too.
----------------------------------------------------------------------------
Topic 14: Manual page inconsistencies
STATE: DISCUSSION
REF: cf. bug #12370
In order to get the manual pages registered in the whatis database it is
necessary, that the manual pages specify the correct name and section with
the `.SH' command.
At the moment, some manual pages don't have a .SH section.
For consistency reasons it is suggested, that all manual pages specify the
same name and section in the manual page as what is used in the file name.
As the sections that are supported by the `man' command are handcoded into
`man' we have to coordinate the use of manual page sections.
The following policy has been suggested:
Maintainers should check that the manpages installed by the package go
registered in the whatis database using a correct
.SH NAME
section and a one-row description, as described in man(7).
In addition, the title of the manual page has to conform to its
file name. For example, the manual page foo.conf(5x) has to use the
name foo.conf.5x.gz and has to contain the command
.TH foo.conf(5x)
Packages introducing a new section name should email the man-db
maintainer <man-db@packages.debian.org> to let him include it in the
static list of manual sections.
----------------------------------------------------------------------------
Topic 15: Documentation policy
STATE: POSTPONED
INFO: The discussion about the implementation of the new documentation
policy will be started on debian-doc soon.
REF: cf. #7890, cf. #11095
----------------------------------------------------------------------------
Topic 16: New source package format
STATE: POSTPONED
The discussion of the following topics has been postponed, until the new
source package format is discussed:
* source dependencies
* new control fields (Author, Upstream-Site, etc.)
----------------------------------------------------------------------------
-- _,, Christian Schwarz
/ o \__ schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
! ___; schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
\ /
\\\______/ ! PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
\ / http://fatman.mathematik.tu-muenchen.de/~schwarz/
-.-.,---,-,-..---,-,-.,----.-.-
"DIE ENTE BLEIBT DRAUSSEN!"
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-request@lists.debian.org . Trouble?
e-mail to templin@bucknell.edu .
Reply to: