<?xml version="1.0"?>
<!DOCTYPE webpage
  PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
    "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">

<webpage id="developers-pkgsrc-index">
<config param="desc" value="NetBSD pkgsrc Developer Information"/>
<config param="cvstag" value="$NetBSD: index.xml,v 1.35 2008/10/17 06:50:49 mishka Exp $"/>
<config param="rcsdate" value="$Date: 2008/10/17 06:50:49 $"/>
<head>
  <!-- Copyright (c) 1994-2004
       The NetBSD Foundation, Inc.  ALL RIGHTS RESERVED. -->
  <title>NetBSD pkgsrc Developer Information</title>
</head>

<sect1 role="toc">
  <sect2 id="oberview">
    <title>Overview</title>

    <sect3 id="introduction">
      <title>Introduction</title>

      <para>This page contains pointers to various pkgsrc related material.
	The information here is likely to be most useful for pkgsrc
	developers.</para>
    </sect3>

    <sect3 id="status">
      <title>Status</title>

<!--
      <para>The NetBSD Packages Collection is currently
	<emphasis role="bold">frozen</emphasis>
	since <ulink url="http://mail-index.NetBSD.org/tech-pkg/2008/09/17/msg001706.html">2008-09-17</ulink>.
	See <ulink url="#goals">below for details</ulink>.</para>
-->
      <para>The NetBSD Packages Collection is currently
	<emphasis role="bold">open</emphasis>. Latest stable
	branch is &pkgsrc.branch.latest;.</para>
    </sect3>
  </sect2>

  <sect2 id="freeze">
    <title>pkgsrc freeze guidelines</title>

    <sect3 id="goals">
      <title>Goals</title>

      <para>The primary goal of the pkgsrc freeze is to produce the 
	next stable branch of pkgsrc. Commits to the pkgsrc HEAD 
	during a freeze should be aimed at reducing the open
	<ulink url="../../Gnats/category/pkg.html">pkgsrc-related PR</ulink>
	count and reducing the number of broken packages in the bulk 
	builds.</para>
    </sect3>

    <sect3 id="rules">
      <title>Rules</title>
      
      <orderedlist>
	<listitem>No infrastructure changes nor new packages should be 
	  committed. This includes non-trivial changes to 
	  <filename>buildlink3.mk</filename> files.</listitem>
	  
	<listitem>Package updates are only allowed for leaf packages 
	  or for packages with security issues. For non-leaf packages
	  approval must be asked for and given (by pkgsrc-pmc) on the <ulink
	  url="mailto:packages@NetBSD.org">pkgsrc developers</ulink>
	  mailing list.</listitem>
	
	<listitem>Approval requests to the
	  <ulink url="mailto:packages@NetBSD.org">pkgsrc developers</ulink>
	  mailing list must answer the following questions:

	  <itemizedlist>
	    <listitem>Why is it critical to update this package for the 
	      upcoming branch?</listitem>
	    <listitem>What changes should be expected between the current 
	      version and the updated version?</listitem>
	  </itemizedlist>
	</listitem>

	<listitem>Commits should only be made to fix portability issues,
	  build problems, or for addressing open PRs.</listitem>
	
	<listitem>Commit messages should note explicitly why the commits 
	  were made during the freeze period, and if necessary, who 
	  gave the approval, e.g.:
	  
	  <itemizedlist>
	    <listitem><quote>Updated during the freeze to fix security issue
	      noted at http://...; approved by ...</quote></listitem>
	    <listitem><quote>Updated during the freeze to fix problem noted
	      n pkg/NNNNN; approved by ...</quote></listitem>
	    <listitem><quote>Fix build on Darwin due to issues with
	      <filename>namesrv8_compat.h</filename></quote></listitem>
	  </itemizedlist>
	</listitem>

	<listitem>The pkgsrc <quote>regress</quote> and <quote>doc</quote>
	  categories are exempt from the freeze.</listitem>
      </orderedlist>
    </sect3>

    <sect3 id="branch-todo">
      <title>Things to do when branching</title>

      <itemizedlist>
	<listitem>Send an announcement to
	  <email>netbsd-announce@NetBSD.org</email>.</listitem>
	<listitem>Send an announcement to <email>www@NetBSD.org</email> or 
	  make the website announcement yourself (see <ulink 
	  url="../htdocs.html#adding-news-items">this link</ulink>).</listitem>
	<listitem>Update
	  <filename>htdocs/share/xml/misc.ent</filename>;
	  regen <filename>htdocs/docs/software/packages.html</filename> and commit.</listitem>
	<listitem>Update
	  <filename>htdocs/developers/pkgsrc/index.xml</filename>; 
	  commit <filename>index.xml</filename>; regen
	  <filename>index.html</filename> and commit.</listitem>
      </itemizedlist>
    </sect3>
  </sect2>

  <sect2 id="importing-or-updating">
    <title>Importing or updating packages</title>

    <sect3 id="import">
      <title>How to import a new package or update a package</title>
      
      <para>This is explained in detail in the <ulink
      	url="../../docs/pkgsrc/submit.html#committing-importing">pkgsrc Guide</ulink>.</para>
    </sect3>

<!--
      <para>Once you have verified that the package you're about to 
	import is correct (pkglint, tested it, etc.), use the following 
	procedure: <emphasis role="bold">(Do <emphasis>NOT</emphasis> use 
	a series of <quote><code>cvs add</code></quote> 
	commands)</emphasis></para>

      <orderedlist>
	<listitem>Please use <quote><command>pkglint</command></quote> 
	  to test your package before importing it. There must not be any
	  fatal error and there should not be any warning. If you disagree
	  about any of these message please contact the <ulink
	  url="mailto:packages@NetBSD.org">pkgsrc developers</ulink>
	  .</listitem>
	
	<listitem>The <ulink="../../docs/pkgsrc/debug.html">debuggins chapter</ulink> of the <ulink
	  url="../../docs/pkgsrc/">pkgsrc guide</ulink>
	  describes some debugging techniques.
	  Especially the <quote>make print-PLIST</quote> test should be used
	  to verify the completeness of the package list.</listitem>
	
	<listitem>Use the following command to import the package:
	  <programlisting>cvs import pkgsrc/category/pkg TNF pkgsrc-base</programlisting>
	  (where the category and package name again reflect your 
	  package).</listitem>
	
	<listitem>The commit message should include the name, version 
	  number of the package and the COMMENT from 
	  <filename>Makefile</filename>.</listitem>
	
	<listitem>Update <filename>pkgsrc/doc/CHANGES</filename> &mdash; 
	  note this file is parsed by automatic scripts so keep to the 
	  existing format. Times/dates are in UTC.</listitem>
      </orderedlist>

      <caution>The pkgsrc/category/pkg path is a relative path for 
	the cvsroot, <emphasis role="warning">NOT FOR THE FILES YOU
	ARE IMPORTING. YOU MUST BE IN THE TOP LEVEL DIRECTORY OF YOUR 
	PACKAGEWHEN IMPORTING!</emphasis></caution>

      <important><code>cvs import</code> is preferred to 
	<code>cvs add</code> because the former gets everything 
	with a single command, and provides a consistent tag.</important>
    </sect3>

    <sect3 id="update">
      <title>Updating a package</title>

      <orderedlist>
	<listitem>Use pkglint and verify the <filename>PLIST</filename> 
	  is correct.</listitem>
	
	<listitem>If any other package depends upon the one being updated 
	  it is important to ensure that their DEPENDS entries are correct,
	  <emphasis role="bold">otherwise they will no longer be able 
	  to build</emphasis>. If in doubt run 
	  <quote><code>lintpkgsrc -d</code></quote> (part of 
	  pkglint).</listitem>
	<listitem>Update <filename>pkgsrc/doc/CHANGES</filename> &mdash; note
	  this file is parsed by automatic scripts so keep to the existing
	  format. Times/dates are in UTC.</listitem>
      </orderedlist>
    </sect3>
-->
    <sect3 id="pullup">
      <title>Pulling up updates to branches</title>

      <para>Critical bug fixes, security updates, and build fixes can be 
	pulled up to the latest stable pkgsrc branch. Please forward 
	the <quote>cvs commit</quote> mail from the pkgsrc-changes 
	mailing list to the <ulink 
	url="mailto:pullup-pkgsrc@NetBSD.org">pullup</ulink> address.</para>

      <para>The pkgsrc pullup ticket tracking summaries are found by adding
	<quote>req/index-pkgsrc.html</quote> to the 
	http://releng.NetBSD.org/ URL. (Not directly linked to avoid 
	automated e-mail spidering.)</para>
    </sect3>
  </sect2>

  <sect2 id="bulk-builds">
    <title>Bulk pkgsrc builds</title>

    <sect3 id="bulkhowto">
      <title>Setting up a bulk pkgsrc build</title>

      <para>The <ulink
      url="../../docs/pkgsrc/bulk.html">bulkbuild chapter</ulink>
      of the <ulink 
	url="../../docs/pkgsrc/">pkgsrc guide</ulink>
	describes how to set up a bulk pkgsrc build.</para>
    </sect3>

    <sect3 id="bulklogs">
      <title>Currently Available Bulk Build Results</title>

      <para>The results of various bulk pkgsrc builds are posted to the <ulink
	  url="../../mailinglists/#pkgsrc-bulk">pkgsrc-bulk</ulink>
	  mailing list.</para>
    </sect3>

    <sect3 id="bulk-packages">
      <title>Providing binary packages for ftp.NetBSD.org 
	(bulk-packages)</title>

      <para>We need to coordinate providing a good set of binary packages
	for as many arch/osrev combinations as possible.</para>
      
      <para>It is critical to ensure binary packages are built against the
	same set of depends to avoid install conflicts. The most
	practical way to arrange this is to use the bulk building system
	and upload the complete set of packages after every build.</para>
      
      <para>Developers interested in assisting (all are invited) should
	subscribe to the <email>pkgsrc-bulk@NetBSD.org</email> list, and 
	check <filename>localsrc/admin/bulk-packages</filename> for an
	available arch/osrev combination.</para>

      <sect4 id="conventions">
	<title>bulk-packages conventions:</title>

	<itemizedlist>
	  <listitem>When taking over an arch/osrev combination either start
	    bulk building from scratch, or download the current set of
	    binary packages from ftp.NetBSD.org to 'pre seed' the
	    build process (most useful for slower architectures).</listitem>
	  
	  <listitem>When uploading packages upload/rsync the entire set 
	    of bulk built packages, and delete any other packages for that
	    arch/osrev from ftp.NetBSD.org.</listitem>

	  <listitem>If no longer able to handle a build, remove the entry
	    from <filename>localsrc/admin/bulk-packages</filename> and 
	    notify  pkgsrc-bulk.</listitem>

	  <listitem>Any developer can upload updated/new/security-fix 
	    packages to ftp.NetBSD.org, but they 
	    <emphasis>must</emphasis> be built against the set of binary 
	    packages already present for that arch/osrev.</listitem>
	  
	  <listitem>Machines should run the latest minor release, 
	    or (recommended) track the release branch.</listitem>
	</itemizedlist>
	
	<note><para>This does not address the issue of new versions of
	  binary packages not installing against a user's existing 
	  set of installed depends, or a updated depend potentially 
	  requiring an update of many other packages already installed 
	  in their machine.</para>
	  
	<para>Current options for that would be either freezing binary 
	  packages at tagged values, or having multiple binary package 
	  trees per arch/osrev. The former significantly reduces the 
	  utility of the binary packages, and the latter is not worth 
	  considering until we can get <emphasis>one</emphasis> 
	  consistent tree per arch/osrev.</para></note>
      </sect4>
    </sect3>
  </sect2>

  <sect2 id="weekly-pkgsrc-checks">
    <title>Weekly pkgsrc checks</title>

    <sect3 id="weeklypkgsrc">
      <title>Weekly-pkgsrc script</title>

      <para>
	<ulink url="mailto:dmcmahill@NetBSD.org">&a.dmcmahill;</ulink> 
	maintains a script that is run once a week to perform various 
	pkgsrc consistency checks. The currentset of checks are:</para>
      
      <itemizedlist>
	<listitem><code>DEPENDS</code> &mdash; verifies that all 
	  <code>{BUILD_}DEPENDS</code> are set to valid versions.</listitem>
	
	<listitem><filename>distinfo</filename> &mdash; verifies 
	  distfile checksums and sizes, and that all patches are listed 
	  and their checksums match.</listitem>
	
	<listitem>category makefiles &mdash; verifies all packages are listed 
	  in the category makefiles.</listitem>
	
	<listitem>restricted binary packages &mdash; warns of any restricted 
	  binary packages.</listitem>
	
	<listitem>vulnerable packages &mdash; verifies all vulnerable
	  packages.</listitem>
      </itemizedlist>

      <para>The results of these checks are emailed to NetBSD pkgsrc 
	developers.</para>
    </sect3>
  </sect2>

  <sect2 id="misc">
    <title>Miscellaneous</title>

    <sect3 id="todo">
      <title>Handling the TODO List</title>

      <para>There's a <ulink
	url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/doc/TODO">TODO</ulink>
	list in the pkgsrc doc directory. Feel free to add, and especially
	remove items from there (after solving the mentioned problem, of
	course).</para>
    </sect3>

    <sect3 id="pkg-bug-handler">
      <title>The pkg-bug-handler group</title>

      <para>In order to manage the large number of pkgsrc-related problem 
	reports each day, the <quote>pkg-bug-handler</quote> group 
	has been created.  See <ulink 
	url="pkg-bug-handler.html">this page</ulink> for details.</para>
    </sect3>
  </sect2>
</sect1>
<parentsec url="../" text="NetBSD Developer Documentation"/>
</webpage>

