path: root/doc/guide/files/submit.xml

<!-- $NetBSD: submit.xml,v 1.37 2020/06/20 05:31:10 rillig 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="creating"/> 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="https://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="https://pkgsrc.org/wip/"/>
	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="https://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="commit-messages">
  <title>Commit Messages</title>
  <para>For several years, there have been mirrors of pkgsrc in
  fossil, git, and hg. Standard practise when using these tools is to
  make the first line of a commit message function as a summary that
  can be read without the rest, such as is commonly done with "git log
  --oneline". For this reason, we have the following guidelines for
  pkgsrc commit messages:</para>

  <itemizedlist>
    <listitem><para>Start the commit message with a line that explains the
    big picture in 65 characters or less. When a commit is for one
    package, include the name of the package. For updates, include the
    version to which it is updated.</para></listitem>
    <listitem><para>Leave the next line empty.</para></listitem>
    <listitem><para>Then come the details for the commit (changes in that
    package, reason for a change) and any relevant PRs. Wrap this
    section.</para></listitem>
  </itemizedlist>

  <para>Here is an example:
  <programlisting>
  libxslt: update to 1.0.30

  Changes since 1.0.29:
  ...
  </programlisting>
  </para>

  <para>Here is another example:
  <programlisting>
  mk/bsd.pkg.mk: enable SSP by default on NetBSD

  (rationale)
  </programlisting>
  </para>

  <para>Commit messages are final: no <quote>cvs admin</quote> is
  allowed on the pkgsrc repository to change commit messages.</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 the old name
  in other Makefiles, options, buildlink files, etc.</para>

<para>
  Also, when renaming a package, please add
  the package name and version pattern(s) of the previous package
  to <varname>SUPERSEDES</varname>.
  This may be repeated for multiple renames.
  The new package would be an exact replacement.
  Example:
</para>

<programlisting>
SUPERSEDES+=    p5-IO-Compress-Zlib&lt;2.017
SUPERSEDES+=    optcomp-[0-9]*
</programlisting>

<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>