 @@ -1,243 +1,245 @@
-<!-- $NetBSD: submit.xml,v 1.24 2009/09/17 18:01:18 kano Exp $ -->
+<!-- $NetBSD: submit.xml,v 1.25 2012/06/06 07:39:07 wiz Exp $ -->
 <chapter id="submit"> <?dbhtml filename="submit.html"?>
 <title>Submitting and Committing</title>
 <sect1 id="submitting-binary-packages">
 <title>Submitting binary packages</title>
 	<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 annoy anyone 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. NetBSD
 	developers doing bulk builds and wanting to upload them please
 	see <xref linkend="bulk-upload"/>.</para>
 </sect1>
 <sect1 id="submitting-your-package">
 <title>Submitting source packages (for non-NetBSD-developers)</title>
 	<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 &man.tar.1;
 	archive that contains all files that make up the package.
 	Finally, send this package to the pkgsrc bug tracking system,
 	either with the &man.send-pr.1; command, or if you don't have
 	that, go to the web page
 	<ulink url="http://www.NetBSD.org/support/send-pr.html"/>,
 	which contains some instructions and a link to a form where you
 	can submit packages.  The
 	<filename role="pkg">sysutils/gtk-send-pr</filename> package is
 	also available as a substitute for either of the above two tools.
 	</para>
 	<para>In the form of the problem report, the category should be
 	<quote>pkg</quote>, the synopsis should include the package name
 	and version number, and the description field should contain a
 	short description of your package (contents of the COMMENT
 	variable or DESCR file are OK). The uuencoded package data should
 	go into the <quote>fix</quote> field.</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>
 </sect1>
 <sect1 id="general-notes-for-changes">
 <title>General notes when adding, updating, or removing packages</title>
 	<para>Please note all package additions, updates, moves, and
 	removals in <filename>pkgsrc/doc/CHANGES-<replaceable>YYYY</replaceable></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
 	<filename>pkgsrc/doc/TODO</filename> file and remove the entry
 	for the package you updated or removed, in case it was mentioned
 	there.</para>
 	<para>When the <varname>PKGREVISION</varname> of a package is
 	bumped, the change should appear in
 	<filename>pkgsrc/doc/CHANGES-<replaceable>YYYY</replaceable></filename> if it is security
 	related or otherwise relevant. Mass bumps that result from a
 	dependency being updated should not be mentioned. In all other
 	cases it's the developer's decision.</para>
 <para>There is a make target that helps in creating proper
   <filename>CHANGES-<replaceable>YYYY</replaceable></filename> entries:  <command>make
   changes-entry</command>. It uses the optional <varname>CTYPE</varname>
   and <varname>NETBSD_LOGIN_NAME</varname> variables. The general
   usage is to first make sure that your <filename>CHANGES-<replaceable>YYYY</replaceable></filename>
   file is up-to-date (to avoid having to resolve conflicts later-on)
   and then to <command>cd</command> to the package directory.  For
   package updates, <command>make changes-entry</command> is enough.
   For new packages, or package moves or removals, set the
   <varname>CTYPE</varname> variable on the command line to "Added",
   "Moved", or "Removed".  You can set <varname>NETBSD_LOGIN_NAME</varname>
   in &mk.conf; if your local login name is
   not the same as your NetBSD login name. The target also automatically
   removes possibly existing entries for the package in the
   <filename>TODO</filename> file. Don't forget to commit
   the changes, e.g. by using <command>make changes-entry-commit</command>!
   If you are not using a checkout directly from cvs.NetBSD.org, but e.g.
   a local copy of the repository, you can set USE_NETBSD_REPO=yes. This
   makes the cvs commands use the main repository.
   </para>
 </sect1>
 <sect1 id="committing-importing">
-<title>Committing: Importing a package into CVS</title>
+<title>Committing: Adding a package to CVS</title>
 <para>This section is only of interest for pkgsrc developers with write
-  access to the pkgsrc repository. Please remember that cvs
+  access to the pkgsrc repository.</para>
-  imports files relative to the current working directory, and that
+<para>When the package is finished, <quote>cvs add</quote> the files.
-  the pathname that you
+Start by adding the directory and then files in the directory. Don't
-  give the <command>cvs import</command> command is so that it knows where
+forget to add the new package to the category's
-  to place the files in the repository.  Newly created packages should be
+<filename>Makefile</filename>. Make sure you don't forget any files;
-  imported with a vendor tag of <quote>TNF</quote> and a release tag of
+you can check by running <quote>cvs status</quote>. An example:</para>
   <quote>pkgsrc-base</quote>, e.g:</para>
 <programlisting>
-&uprompt; cd .../pkgsrc/category/pkgname
+&uprompt; cd .../pkgsrc/category
-&uprompt; cvs import pkgsrc/category/pkgname TNF pkgsrc-base
+&uprompt; cvs add pkgname
 &uprompt; cd pkgname
 &uprompt; cvs add DESCR Makefile PLIST distinfo buildlink3.mk patches
 &uprompt; cvs add patches/p*
 &uprompt; cvs status | less
 &uprompt; cd ..
 &uprompt; vi Makefile # add SUBDIRS+=pkgname line
 &uprompt; cvs commit Makefile pkgname
 </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>For new packages, <quote>cvs import</quote> is preferred to <quote>cvs
+<para>Also mention the new package in
-  add</quote> because the former gets everything with a single command,
+<filename>pkgsrc/doc/CHANGES-20xx</filename>.</para>
   and provides a consistent tag.</para>
 <para>Previously, <quote>cvs import</quote> was suggested, but it was
 much easier to get wrong than <quote>cvs add</quote>.</para>
 </sect1>
 <sect1 id="updating-package">
 <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 recognize 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 id="renaming-package">
 <title>Renaming a package in pkgsrc</title>
 <para>Renaming packages is not recommended.</para>
 <para>When renaming packages, be sure to fix any references to old name
   in other Makefiles, options, buildlink files, etc.</para>
 <para>Also When renaming a package, please define
   <varname>SUPERSEDES</varname> to the package name and dewey version
   pattern(s) of the previous package name.
   This may be repeated for multiple renames.
   The new package would be an exact replacement.
 </para>
 <para>Note that <quote>successor</quote> in the
   CHANGES-<replaceable>YYYY</replaceable> file doesn't necessarily
   mean that it <emphasis>supersedes</emphasis>, as that successor may
   not be an exact replacement but is a suggestion for the replaced
   functionality.</para>
 </sect1>
 <sect1 id="moving-package">
 <title>Moving a package in pkgsrc</title>
 <para>It is preferred that packages are not renamed or moved, but if needed
   please follow these steps.
 </para>
 <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>&cprompt; <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>In the modified package's Makefile, consider setting
 <varname>PREV_PKGPATH</varname> to the previous category/package
 pathname.  The <varname>PREV_PKGPATH</varname> can be used by tools
 for doing an update using pkgsrc building; for example, it can
 search the &man.pkg.summary.5; database for <varname>PREV_PKGPATH</varname>
 (if no <varname>SUPERSEDES</varname>) and then use the corresponding
 new <varname>PKGPATH</varname> for that moved package.  Note that
 it may have multiple matches, so the tool should also check on the
 <varname>PKGBASE</varname> too.  The <varname>PREV_PKGPATH</varname>
 probably has no value unless <varname>SUPERSEDES</varname> is not
 set, i.e.  <varname>PKGBASE</varname> stays the same.  </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>&cprompt; <userinput>cd /usr/pkgsrc</userinput>
 &cprompt; <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>&cprompt; <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>