248 lines
10 KiB
XML
248 lines
10 KiB
XML
<!-- $NetBSD: submit.xml,v 1.30 2014/08/12 05:12:41 schmonz 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"/><!-- TODO: was "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 commit-changes-entry</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: Adding a package to CVS</title>
|
|
<para>This section is only of interest for pkgsrc developers with write
|
|
access to the pkgsrc repository.</para>
|
|
<para>When the package is finished, <quote>cvs add</quote> the files.
|
|
Start by adding the directory and then files in the directory. Don't
|
|
forget to add the new package to the category's
|
|
<filename>Makefile</filename>. Make sure you don't forget any files;
|
|
you can check by running <quote>cvs status</quote>. An example:</para>
|
|
<programlisting>
|
|
&uprompt; cd .../pkgsrc/category
|
|
&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; cvs commit
|
|
&uprompt; cd ..
|
|
&uprompt; vi Makefile # add SUBDIRS+=pkgname line
|
|
&uprompt; cvs commit Makefile
|
|
&uprompt; cd pkgname
|
|
&uprompt; make CTYPE=Added commit-changes-entry
|
|
</programlisting>
|
|
|
|
<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>Also mention the new package in
|
|
<filename>pkgsrc/doc/CHANGES-20xx</filename>.</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>
|