Add a file describing the maintenance and administration of pkgsrc branches.

1 files changed, 76 insertions, 0 deletions

diff --git a/doc/BRANCHES b/doc/BRANCHES
new file mode 100644
index 00000000000..5e6623cb103
--- /dev/null
+++ b/doc/BRANCHES
@@ -0,0 +1,76 @@
+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 file.
+
+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