This file explains some of the conventions to follow for those wishing
to contribute to the project.


	RPM spec files.

Our conventions for RPM spec files are quite similar to Red Hat's, but
a few differences and additional requirements for native Owl packages
do exist.

1. Start the spec file with a comment containing the CVS Id keyword,
followed by an empty line.

2. The preferred tag names (whenever synonyms exist) and order of tags
is: Summary, Name, Version, Release, Epoch, License, Group, URL,
Source*, Patch*, PreReq, Requires, Conflicts, Provides, Obsoletes,
Auto*, Prefix, BuildRequires, BuildArchitectures, ExcludeArch,
ExclusiveArch, BuildRoot.  Other tags we (currently) don't use.

3. Release numbers for native Owl packages are of the form:

	owlREVISION

or, when packaging an alpha/beta/prerelease version of a certain piece
of software and the Version tag is set to the upcoming version number:

	owl0.REVISION

or, when updating an older branch of Owl:

	BRANCH_POINT_RELEASE.BRANCH.REVISION

where REVISION is an Owl-specific package revision number incremented
after each update, BRANCH_POINT_RELEASE is the Release string as of
when the branch was created, and BRANCH is the branch version (that
is, "0.1" for Owl 0.1-stable).

When updating to a new Version, REVISION should be reset to 1 and, for
older branches, BRANCH_POINT_RELEASE set to "owl0".

4. The correct BuildRoot tag for an Owl package is:

	BuildRoot: /override/%name-%version

Our build environment will override the BuildRoot regardless of this
tag, but setting it in this way will remind people to override the
BuildRoot for manual builds of the package, especially on non-Owl.

5. Separate tag names and values you set them to with a single space
character.  Use commas (also followed by a space) to separate items in
dependency lists.  Do terminate Summary lines with a dot.  In both
Summary and %description (as well as in any other documentation),
avoid capitalizing the names of commands, even if they happen to be
the first word in a sentence, unless the capitalized form is the
official name for the software in question.  Use double spaces to
separate sentences.

6. Our build environment sets the C/C++ compiler optimization flags in
%optflags in a way that is optimal for compiling standalone programs
and doesn't produce too much warnings with typical source files.  When
building libraries, another set of optimization flags may be used by
placing the following two lines right before the %build section:

	# Use optflags_lib for this package if defined.
	%{expand:%%define optflags %{?optflags_lib:%optflags_lib}%{!?optflags_lib:%optflags}}

This will disable optimizations that would prevent debugging of
programs linked against the libraries (even when the programs
themselves are correctly built for debugging) and, on the x86, will
ensure stack alignment suitable for efficient floating-point and MMX
operations that a program linked against the library may do.  (The
latter is just to be friendly to third-party programs.  We don't have
a noticeable amount of floating-point math in programs that are a part
of Owl and thus we don't do the extra stack alignment when building
our programs.  But libraries need to be different because of possible
callbacks.)

It also is recommended that you make the source files clean enough to
not produce a single compiler warning when building with "gcc -Wall".
If you do, then the right way to pass the -Wall is in most cases by
placing the following line right before the %build section:

	%{expand:%%define optflags %optflags -Wall}

7. Subshells in build, pre/post-install/uninstall, and trigger scripts
are to be avoided by all means as they mask possible errors.  If you
intended to use a subshell to temporarily change current directory,
use pushd and popd commands instead.  If you really must use a
subshell, it is suggested that you propagate the status of commands it
runs to the parent shell manually.

8. Use tabs to indent conditional blocks and continuation lines in
scripts.

9. Use -eq or -ne and not = or != to compare numeric values.  In
particular, this applies to the $1 argument that RPM itself passes to
scripts.  And don't place the $1 in quotes, the package has to trust
its package manager to pass it the correct input anyway.

10. In %changelog entry dates, use two digits for day of month with a
leading zero if necessary.

11. In %changelog, when adding new entries do specify the current
package Version and Release after your e-mail address, like this:

* Mon Mar 10 2003 Your Name <you@example.com> 0.6.2-owl1


	Patch file naming.

Use the following syntax for patch file names:

	NAME-VERSION-ORIGIN-WHAT.diff

where NAME and VERSION are the package name and version, ORIGIN is an
abbreviation of the distribution name(s) the patch originates from,
and WHAT is a description of what the patch is for or what it does.

If a single patch file is based on pieces from more than one
distribution, all are to be included in ORIGIN in order of relevance.
For patches developed as a part of Owl, ORIGIN is to be set to "owl".
If a patch is derived from another distribution but with significant
changes applied, ORIGIN should include "-owl-" as well (which would
indicate that any bugs are ours).  If a patch has been extracted from
the primary CVS repository for the package in question (for example,
this may be the case for various back-ports), ORIGIN should be set to
"cvs" and WHAT to the date it corresponds to (as YYYYMMDD) plus the
usual description of the patch.  Patches from upstream maintainers
that aren't (yet?) in the primary CVS repository (if one even exists)
may have ORIGIN set to "up".

There're also some common WHATs to use whenever applicable:

Makefile	- Makefile* patches only (note the capitalization)
bound		- bound checking (buffer and/or integer overflow fixes)
config		- configuration files patches only (compile- or runtime)
doc		- documentation patches only
fixes		- cumulative bug, reliability, and/or security patches
format		- printf-style format string fixes (not only security)
info		- texinfo documentation patches only
install-no-root	- changes to run "make install" or equivalent as non-root
linux		- changes needed to build on Linux (for ported software)
man		- man page patches only
tmp		- patches dealing with temporary file handling issues
vitmp		- patches that add vitmp(1) support
warnings	- compilation warning fixes only

This is NOT to suggest you should try to arrange your modifications
such that the patch files fit one of these categories.  In fact, it is
often preferable to do things differently.  This is just to say that
if you happen to have a patch file that matches one of the categories,
name it accordingly (such as, "tmp" and not, say, "mkstemp").


	(Re-)generating patch files.

The patch files should be generated with:

	TZ=UTC diff -urpN NAME-VERSION.orig NAME-VERSION >
		NAME-VERSION-ORIGIN-WHAT.diff

where NAME-VERSION.orig and NAME-VERSION are directories with the
original and modified versions of the upstream package, respectively.
The "-p" and "-N" options to diff(1) may be omitted if not applicable.

When re-generating patches to apply additional changes, the existing
patches should be applied with "patch -Z", for example like this:

	cd NAME-VERSION
	patch -p1 -Z < ../NAME-VERSION-ORIGIN-WHAT.diff

The use of timestamps in UTC lets us better preserve them over patch
file updates and reduces the amount of changes between revisions.


	C source code formatting.

When developing or importing pieces of C code for further maintenance
as a part of Owl, indent(1) may initially be used with the following
options:

	indent -kr -i8 -nlp -nbbo -l79 -lc79

This does not exactly match our preferred coding style and thus isn't
to be used on sources already in Owl.


	Temporary file handling.

It's better to not use temporary files, however if you must, the
preferred way to do it from shell scripts is with code like this:

TMPFILE=
trap 'rm -f -- "$TMPFILE"' EXIT
trap 'trap - EXIT; rm -f -- "$TMPFILE"; exit 1' HUP INT QUIT TERM
TMPFILE="`mktemp -t program.XXXXXXXXXX`" || exit

This may be used in our own scripts or in patches.  The package should
then require the proper version of mktemp(1):

Requires: mktemp >= 1:1.3.1

As usual, use Requires, PreReq, and/or BuildRequires depending on
where in the package the uses of mktemp occur.

$Id: CONVENTIONS,v 1.17.2.1 2004/04/13 21:44:25 solar Exp $
