doc/BRANCHES

   1 pkgsrc branches
   2 ===============
   3
   4 This short document gives a brief overview of how branches are used in
   5 pkgsrc, what changes should be pulled up to branches from the head,
   6 and, in general, provides administrative background for pkgsrc
   7 branches.
   8
   9 Starting in December 2003, we have been branching pkgsrc every 3
  10 months.  The reasoning behind this is that pkgsrc needs to be branched
  11 more often than the main NetBSD source tree, to enable it to keep up
  12 with more frequent releases from third-party software authors, to
  13 enable it to keep up to date with security fixes (see also
  14 pkgsrc/security/audit-packages for help with this), and for general
  15 bug fixes in third-party software.  In addition, users are accustomed
  16 to updating their packages more frequently than their main trees, and
  17 so this move is intended to mirror the habits and usage model of
  18 pkgsrc users.
  19
  20 pkgsrc branches are traditionally made at the end of almost 3 months
  21 development - new packages added, some old packages removed, and many
  22 packages updated to newer versions. At the end of this development
  23 period, a freeze is placed on new additions to pkgsrc, and any packages
  24 which have problems in them are investigated, and the team will fix as
  25 many of the errors as possible.  The aim is to have zero broken
  26 packages on its main platform (NetBSD/i386, using the latest release
  27 available at the time of pkgsrc-branching).  In the past, we have
  28 achieved this aim - recently, with newer versions of gcc, and other
  29 changes in the base system, we have had to relax that goal. Starting
  30 with the pkgsrc-2004Q2 branch, the freeze start and end times are
  31 recorded in the pkgsrc/doc/CHANGES-* files.
  32
  33 The pkgsrc branch is named according to the time period at the end of
  34 which it was made:  pkgsrc-2003Q4, pkgsrc-2004Q1 etc.  This is
  35 reflected in the CVS tag and branch name in the pkgsrc tree.  Commits
  36 to the branch appear in pkgsrc-changes mail with the tag in the
  37 subject line.
  38
  39 Only one pkgsrc branch is maintained at any one time.  When the pkgsrc
  40 tree is tagged and branched, the old branch is deprecated, support for
  41 it is ended, and the new branch is supported.
  42
  43 We continually run bulk-builds of pkgsrc on a number of platforms, and
  44 the results are distributed to the pkgsrc-bulk mailing list.
  45
  46 Whilst pkgsrc has been ported to many different operating systems, its
  47 primary use is as the packaging system for NetBSD, and that is where
  48 it gets most exercise.
  49
  50 Where a change has been made to the pkgsrc trunk, and is found to be
  51 working, it can be pulled up to the branch. The developer who wishes
  52 it to be pulled up should send a mail to the well-known address (not
  53 listed here due to spiders and other bots which could harvest the
  54 mail address).
  55
  56 Normally, a security fix will be pulled up to the branch when it is
  57 known that a fix works and closes the security hole. Other bug fixes
  58 and enhancements will enter a "cooling-off period" of two working days
  59 from receipt of the pullup request.  Developers requesting pullups
  60 should take note of this - if you are requesting that a security fix
  61 be pulled up, please mark the request as being for a "security fix".
  62 The criterion for acceptance of a pullup is a simple one - does it
  63 enhance the pkgsrc branch?  - and the pullup manager's decision is
  64 subjective and final.  To request a pullup, the developer should
  65 forward all pieces of the relevant pkgsrc-changes mail marking it
  66 clearly as "security fix", "portability fix" or "other".
  67
  68 Starting with the pkgsrc-2004Q2 branch, on the pkgsrc branch, in the
  69 pkgsrc/doc directory, there will be a file called CHANGES-<branch
  70 name> which contains a short description of the pullup ticket (used
  71 internally to manage the pullup queue), and the date on which it was
  72 taken. This file will also include the exact time in UTC when a branch
  73 was taken, to aid in any date-based CVS operations.
  74
  75 Alistair Crooks
  76 Sun Jul 18 23:31:49 BST 2004