pkgsrc/doc/BRANCHES

pkgsrc branches
===============

This short document gives a brief overview of how branches are used in
pkgsrc, what changes should be pulled up to branches from the head,
and, in general, provides administrative background for pkgsrc
branches.

Starting in December 2003, we have been branching pkgsrc every 3
months.  The reasoning behind this is that pkgsrc needs to be branched
more often than the main NetBSD source tree, to enable it to keep up
with more frequent releases from third-party software authors, to
enable it to keep up to date with security fixes (see also
pkgsrc/security/audit-packages for help with this), and for general
bug fixes in third-party software.  In addition, users are accustomed
to updating their packages more frequently than their main trees, and
so this move is intended to mirror the habits and usage model of
pkgsrc users.

pkgsrc branches are traditionally made at the end of almost 3 months
development - new packages added, some old packages removed, and many
packages updated to newer versions. At the end of this development
period, a freeze is placed on new additions to pkgsrc, and any packages
which have problems in them are investigated, and the team will fix as
many of the errors as possible.  The aim is to have zero broken
packages on its main platform (NetBSD/i386, using the latest release
available at the time of pkgsrc-branching).  In the past, we have
achieved this aim - recently, with newer versions of gcc, and other
changes in the base system, we have had to relax that goal. Starting
with the pkgsrc-2004Q2 branch, the freeze start and end times are
recorded in the pkgsrc/doc/CHANGES-* files.

The pkgsrc branch is named according to the time period at the end of
which it was made:  pkgsrc-2003Q4, pkgsrc-2004Q1 etc.  This is
reflected in the CVS tag and branch name in the pkgsrc tree.  Commits
to the branch appear in pkgsrc-changes mail with the tag in the
subject line.

Only one pkgsrc branch is maintained at any one time.  When the pkgsrc
tree is tagged and branched, the old branch is deprecated, support for
it is ended, and the new branch is supported.

We continually run bulk-builds of pkgsrc on a number of platforms, and
the results are distributed to the pkgsrc-bulk mailing list.

Whilst pkgsrc has been ported to many different operating systems, its
primary use is as the packaging system for NetBSD, and that is where
it gets most exercise.

Where a change has been made to the pkgsrc trunk, and is found to be
working, it can be pulled up to the branch. The developer who wishes
it to be pulled up should send a mail to the well-known address (not
listed here due to spiders and other bots which could harvest the
mail address).

Normally, a security fix will be pulled up to the branch when it is
known that a fix works and closes the security hole. Other bug fixes
and enhancements will enter a "cooling-off period" of two working days
from receipt of the pullup request.  Developers requesting pullups
should take note of this - if you are requesting that a security fix
be pulled up, please mark the request as being for a "security fix".
The criterion for acceptance of a pullup is a simple one - does it
enhance the pkgsrc branch?  - and the pullup manager's decision is
subjective and final.  To request a pullup, the developer should
forward all pieces of the relevant pkgsrc-changes mail marking it
clearly as "security fix", "portability fix" or "other".

Starting with the pkgsrc-2004Q2 branch, on the pkgsrc branch, in the
pkgsrc/doc directory, there will be a file called CHANGES-<branch
name> which contains a short description of the pullup ticket (used
internally to manage the pullup queue), and the date on which it was
taken. This file will also include the exact time in UTC when a branch
was taken, to aid in any date-based CVS operations.

Alistair Crooks
Sun Jul 18 23:31:49 BST 2004