pkgsrc/doc/guide/files/submit.xml

<!-- $NetBSD: submit.xml,v 1.2 2004/10/22 00:24:48 hubertf Exp $ -->

<chapter id="submit"> <?dbhtml filename="submit.html"?>
<title>Submitting and Committing</title>

<sect1>
<title>Submitting your packages</title>
<para>
You have to separate between binary and <quote>normal</quote> (source)
packages here:
</para>

<itemizedlist>
<listitem>
<para>precompiled binary packages</para>
<para>
  Our policy is that we accept binaries only from pkgsrc developers to
  guarantee that the packages don't contain any trojan horses etc. 
  This is not to piss anyone off but rather to protect our users!
  You're still free to put up your home-made binary packages and tell
  the world where to get them. 
</para>
</listitem>

<listitem>
<para>packages</para>
<para>
  First, check that your package is complete, compiles and runs well;
  see <xref linkend="debug"/> and the rest of this document. Next,
  generate an uuencoded gzipped tar(1) archive, preferably with all files
  in a single directory.
  Finally, <command>send-pr</command> with category <quote>pkg</quote>, a
  synopsis which includes the package name and version number, a short
  description of your package (contents of the COMMENT variable or DESCR
  file are OK) and attach the archive to your PR.
</para>

<para>
  If you want to submit several packages, please send a separate PR for
  each one, it's easier for us to track things that way.
</para>

<para>
  Alternatively, you can also import new packages into pkgsrc-wip
  (<quote>pkgsrc work-in-progress</quote>); see the homepage at <ulink
  url="http://pkgsrc-wip.sourceforge.net/"/> for details.
</para>
</listitem>
</itemizedlist>

</sect1>

<sect1>
<title>Committing: Importing a package into CVS</title>
<para>
  This section is only of interest for pkgsrc developers with write
  access to the pkgsrc repository. Please remember that cvs
  imports files relative to the current working directory, and that
  the pathname that you 
  give the <command>cvs import</command> command is so that it knows where
  to place the files in the repository.  Newly created packages should be
  imported with a vendor tag of <quote>TNF</quote> and a release tag of
  <quote>pkgsrc-base</quote>, e.g:
</para>

<programlisting>
  % cd .../pkgsrc/category/pkgname
  % cvs import pkgsrc/category/pkgname TNF pkgsrc-base
</programlisting>

<para>
  Remember to move the directory from which you imported out of
  the way, or cvs will complain the next time you <quote>cvs
  update</quote> your source tree.  Also don't forget to add the new
  package to the category's <filename>Makefile</filename>.
</para>

<para>
  The commit message of the initial import should include part of the
  <filename>DESCR</filename> file, so people reading the mailing lists know
  what the package is/does.
</para>

<para>
  Please note all package updates/additions in
  <filename>pkgsrc/doc/CHANGES</filename>. It's very
  important to keep this file up to date and conforming to the existing
  format, because it will be used by scripts to automatically update pages on
  <ulink url="http://www.NetBSD.org/">www.NetBSD.org</ulink> and other
  sites. Additionally, check the pkgsrc/doc/TODO file and remove the entry
  for the package you updated, in case it was mentioned there.
</para>

<para>
  For new packages, <quote>cvs import</quote> is preferred to <quote>cvs
  add</quote> because the former gets everything with a single command,
  and provides a consistent tag.
</para>
</sect1>

<sect1>
<title>Updating a package to a newer version</title>
<para>
  Please always put a concise, appropriate and relevant summary of the
  changes between old and new versions into the commit log when updating
  a package. There are various reasons for this:
</para>

<itemizedlist>
<listitem>
<para>
  A URL is volatile, and can change over time. It may go away completely 
  or its information may be overwritten by newer information.
</para>
</listitem>

<listitem>
<para>
  Having the change information between old and new versions in our CVS
  repository is very useful for people who use either cvs or anoncvs.
</para>
</listitem>

<listitem>
<para>
  Having the change information between old and new versions in our CVS
  repository is very useful for people who read the pkgsrc-changes mailing
  list, so that they can make tactical decisions about when to upgrade
  the package.
</para>
</listitem>
</itemizedlist>

<para>
  Please also recognise that, just because a new version of a package
  has been released, it should not automatically be upgraded in the CVS
  repository.  We prefer to be conservative in the packages that are
  included in pkgsrc - development or beta packages are not really the
  best thing for most places in which pkgsrc is used. Please use your
  judgement about what should go into pkgsrc, and bear in mind that
  stability is to be preferred above new and possibly untested features.
</para>
</sect1>

<sect1>
<title>Moving a package in pkgsrc</title>

<orderedlist>
<listitem><para>Make a copy of the directory somewhere else.</para></listitem>

<listitem><para>Remove all CVS dirs.</para>
<para>
  Alternatively to the first two steps you can also do:
</para>
<screen><prompt>%</prompt> <userinput>cvs -d user@cvs.NetBSD.org:/cvsroot export -D today pkgsrc/category/package</userinput></screen>
<para>
  and use that for further work.
</para>
</listitem>

<listitem><para>Fix <varname>CATEGORIES</varname> and any
<varname>DEPENDS</varname> paths that just did <quote>../package</quote>
instead of <quote>../../category/package</quote>.</para>
</listitem>

<listitem><para><command>cvs import</command> the modified package in the new
place.</para></listitem>

<listitem><para>Check if any package depends on it:
<screen><prompt>%</prompt> <userinput>cd /usr/pkgsrc</userinput>
<prompt>%</prompt> <userinput>grep /package */*/Makefile* */*/buildlink*</userinput></screen>
</para>
</listitem>

<listitem><para>Fix paths in packages from step 5 to point to new location.</para></listitem>

<listitem><para><command>cvs rm (-f)</command> the package at the old location.</para></listitem>

<listitem><para>Remove from <filename>oldcategory/Makefile</filename>.</para></listitem>

<listitem><para>Add to <filename>newcategory/Makefile</filename>.</para></listitem>

<listitem><para>Commit the changed and removed files:</para>
<screen><prompt>%</prompt> <userinput>cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile</userinput></screen>
<para>
  (and any packages from step 5, of course).
</para>
</listitem>
</orderedlist>

</sect1>

</chapter>