Annotation of htdocs/docs/pkgsrc/submit.html, revision 1.8

1.1       dsieger     1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
                      2: <html>
                      3: <head>
                      4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
1.4       rillig      5: <title>Chapter 21. Submitting and Committing</title>
1.2       rillig      6: <link rel="stylesheet" href="/global.css" type="text/css">
1.1       dsieger     7: <meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
1.6       rillig      8: <link rel="home" href="index.html" title="The pkgsrc guide">
1.1       dsieger     9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
1.4       rillig     10: <link rel="prev" href="debug.html" title="Chapter 20. Debugging">
                     11: <link rel="next" href="devfaq.html" title="Chapter 22. Frequently Asked Questions">
1.1       dsieger    12: </head>
                     13: <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
                     14: <div class="navheader">
                     15: <table width="100%" summary="Navigation header">
1.4       rillig     16: <tr><th colspan="3" align="center">Chapter 21. Submitting and Committing</th></tr>
1.1       dsieger    17: <tr>
                     18: <td width="20%" align="left">
                     19: <a accesskey="p" href="debug.html">Prev</a> </td>
                     20: <th width="60%" align="center">Part II. The pkgsrc developer's guide</th>
                     21: <td width="20%" align="right"> <a accesskey="n" href="devfaq.html">Next</a>
                     22: </td>
                     23: </tr>
                     24: </table>
                     25: <hr>
                     26: </div>
                     27: <div class="chapter" lang="en">
                     28: <div class="titlepage"><div><div><h2 class="title">
1.4       rillig     29: <a name="submit"></a>Chapter 21. Submitting and Committing</h2></div></div></div>
1.1       dsieger    30: <div class="toc">
                     31: <p><b>Table of Contents</b></p>
                     32: <dl>
1.4       rillig     33: <dt><span class="sect1"><a href="submit.html#submitting-binary-packages">21.1. Submitting binary packages</a></span></dt>
                     34: <dt><span class="sect1"><a href="submit.html#submitting-your-package">21.2. Submitting source packages (for non-NetBSD-developers)</a></span></dt>
                     35: <dt><span class="sect1"><a href="submit.html#general-notes-for-changes">21.3. General notes when adding, updating, or removing packages</a></span></dt>
                     36: <dt><span class="sect1"><a href="submit.html#committing-importing">21.4. Committing: Importing a package into CVS</a></span></dt>
                     37: <dt><span class="sect1"><a href="submit.html#updating-package">21.5. Updating a package to a newer version</a></span></dt>
1.7       snj        38: <dt><span class="sect1"><a href="submit.html#renaming-package">21.6. Renaming a package in pkgsrc</a></span></dt>
                     39: <dt><span class="sect1"><a href="submit.html#moving-package">21.7. Moving a package in pkgsrc</a></span></dt>
1.1       dsieger    40: </dl>
                     41: </div>
                     42: <div class="sect1" lang="en">
                     43: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4       rillig     44: <a name="submitting-binary-packages"></a>21.1. Submitting binary packages</h2></div></div></div>
1.1       dsieger    45: <p>Our policy is that we accept binaries only from pkgsrc
                     46:        developers to guarantee that the packages don't contain any
                     47:        trojan horses etc. This is not to annoy anyone but rather to
                     48:        protect our users! You're still free to put up your home-made
                     49:        binary packages and tell the world where to get them. NetBSD
                     50:        developers doing bulk builds and wanting to upload them please
1.5       hubertf    51:        see <a class="xref" href="bulk.html#bulk-upload" title="7.3.8. Uploading results of a bulk build">Section 7.3.8, &#8220;Uploading results of a bulk build&#8221;</a>.</p>
1.1       dsieger    52: </div>
                     53: <div class="sect1" lang="en">
                     54: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4       rillig     55: <a name="submitting-your-package"></a>21.2. Submitting source packages (for non-NetBSD-developers)</h2></div></div></div>
1.1       dsieger    56: <p>First, check that your package is complete, compiles and
1.5       hubertf    57:        runs well; see <a class="xref" href="debug.html" title="Chapter 20. Debugging">Chapter 20, <i>Debugging</i></a> and the rest of this
                     58:        document. Next, generate an uuencoded gzipped <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">tar</span>(1)</span></a>
1.1       dsieger    59:        archive that contains all files that make up the package.
                     60:        Finally, send this package to the pkgsrc bug tracking system,
1.5       hubertf    61:        either with the <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">send-pr</span>(1)</span></a> command, or if you don't have
1.1       dsieger    62:        that, go to the web page
1.5       hubertf    63:        <a class="ulink" href="http://www.NetBSD.org/support/send-pr.html" target="_top">http://www.NetBSD.org/support/send-pr.html</a>,
1.8     ! snj        64:        which contains some instructions and a link to a form where you
        !            65:        can submit packages.  The
        !            66:        <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/sysutils/gtk-send-pr/README.html" target="_top"><code class="filename">sysutils/gtk-send-pr</code></a> package is
        !            67:        also available as a substitute for either of the above two tools.
        !            68:        </p>
1.1       dsieger    69: <p>In the form of the problem report, the category should be
                     70:        &#8220;<span class="quote">pkg</span>&#8221;, the synopsis should include the package name
                     71:        and version number, and the description field should contain a
                     72:        short description of your package (contents of the COMMENT
                     73:        variable or DESCR file are OK). The uuencoded package data should
                     74:        go into the &#8220;<span class="quote">fix</span>&#8221; field.</p>
                     75: <p>If you want to submit several packages, please send a
                     76:        separate PR for each one, it's easier for us to track things
                     77:        that way.</p>
                     78: <p>Alternatively, you can also import new packages into
                     79:        pkgsrc-wip (&#8220;<span class="quote">pkgsrc work-in-progress</span>&#8221;); see the
1.5       hubertf    80:        homepage at <a class="ulink" href="http://pkgsrc-wip.sourceforge.net/" target="_top">http://pkgsrc-wip.sourceforge.net/</a>
1.1       dsieger    81:        for details.</p>
                     82: </div>
                     83: <div class="sect1" lang="en">
                     84: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4       rillig     85: <a name="general-notes-for-changes"></a>21.3. General notes when adding, updating, or removing packages</h2></div></div></div>
1.1       dsieger    86: <p>Please note all package additions, updates, moves, and
                     87:        removals in <code class="filename">pkgsrc/doc/CHANGES-<em class="replaceable"><code>YYYY</code></em></code>. It's very
                     88:        important to keep this file up to date and conforming to the
                     89:        existing format, because it will be used by scripts to
1.5       hubertf    90:        automatically update pages on <a class="ulink" href="http://www.NetBSD.org/" target="_top">www.NetBSD.org</a> and other
1.1       dsieger    91:        sites. Additionally, check the
                     92:        <code class="filename">pkgsrc/doc/TODO</code> file and remove the entry
                     93:        for the package you updated or removed, in case it was mentioned
                     94:        there.</p>
                     95: <p>When the <code class="varname">PKGREVISION</code> of a package is
                     96:        bumped, the change should appear in
                     97:        <code class="filename">pkgsrc/doc/CHANGES-<em class="replaceable"><code>YYYY</code></em></code> if it is security
                     98:        related or otherwise relevant. Mass bumps that result from a
                     99:        dependency being updated should not be mentioned. In all other
                    100:        cases it's the developer's decision.</p>
                    101: <p>There is a make target that helps in creating proper
1.5       hubertf   102:   <code class="filename">CHANGES-<em class="replaceable"><code>YYYY</code></em></code> entries:  <span class="command"><strong>make
1.1       dsieger   103:   changes-entry</strong></span>. It uses the optional <code class="varname">CTYPE</code>
                    104:   and <code class="varname">NETBSD_LOGIN_NAME</code> variables. The general
                    105:   usage is to first make sure that your <code class="filename">CHANGES-<em class="replaceable"><code>YYYY</code></em></code>
                    106:   file is up-to-date (to avoid having to resolve conflicts later-on)
1.5       hubertf   107:   and then to <span class="command"><strong>cd</strong></span> to the package directory.  For
                    108:   package updates, <span class="command"><strong>make changes-entry</strong></span> is enough.
1.1       dsieger   109:   For new packages, or package moves or removals, set the
                    110:   <code class="varname">CTYPE</code> variable on the command line to "Added",
                    111:   "Moved", or "Removed".  You can set <code class="varname">NETBSD_LOGIN_NAME</code>
1.5       hubertf   112:   in <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a> if your local login name is
1.1       dsieger   113:   not the same as your NetBSD login name. Don't forget to commit
                    114:   the changes to <code class="filename">pkgsrc/doc/CHANGES-<em class="replaceable"><code>YYYY</code></em></code>!</p>
                    115: </div>
                    116: <div class="sect1" lang="en">
                    117: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4       rillig    118: <a name="committing-importing"></a>21.4. Committing: Importing a package into CVS</h2></div></div></div>
1.1       dsieger   119: <p>This section is only of interest for pkgsrc developers with write
                    120:   access to the pkgsrc repository. Please remember that cvs
                    121:   imports files relative to the current working directory, and that
                    122:   the pathname that you
1.5       hubertf   123:   give the <span class="command"><strong>cvs import</strong></span> command is so that it knows where
1.1       dsieger   124:   to place the files in the repository.  Newly created packages should be
                    125:   imported with a vendor tag of &#8220;<span class="quote">TNF</span>&#8221; and a release tag of
                    126:   &#8220;<span class="quote">pkgsrc-base</span>&#8221;, e.g:</p>
                    127: <pre class="programlisting">
                    128: <code class="prompt">$</code> cd .../pkgsrc/category/pkgname
                    129: <code class="prompt">$</code> cvs import pkgsrc/category/pkgname TNF pkgsrc-base
                    130: </pre>
                    131: <p>Remember to move the directory from which you imported out of
                    132:   the way, or cvs will complain the next time you &#8220;<span class="quote">cvs
                    133:   update</span>&#8221; your source tree.  Also don't forget to add the new
                    134:   package to the category's <code class="filename">Makefile</code>.</p>
                    135: <p>The commit message of the initial import should include part of the
                    136:   <code class="filename">DESCR</code> file, so people reading the mailing lists know
                    137:   what the package is/does.</p>
                    138: <p>For new packages, &#8220;<span class="quote">cvs import</span>&#8221; is preferred to &#8220;<span class="quote">cvs
                    139:   add</span>&#8221; because the former gets everything with a single command,
                    140:   and provides a consistent tag.</p>
                    141: </div>
                    142: <div class="sect1" lang="en">
                    143: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4       rillig    144: <a name="updating-package"></a>21.5. Updating a package to a newer version</h2></div></div></div>
1.1       dsieger   145: <p>Please always put a concise, appropriate and relevant summary of the
                    146:   changes between old and new versions into the commit log when updating
                    147:   a package. There are various reasons for this:</p>
                    148: <div class="itemizedlist"><ul type="disc">
                    149: <li><p>A URL is volatile, and can change over time. It may go away completely
                    150:   or its information may be overwritten by newer information.</p></li>
                    151: <li><p>Having the change information between old and new versions in our CVS
                    152:   repository is very useful for people who use either cvs or anoncvs.</p></li>
                    153: <li><p>Having the change information between old and new versions in our CVS
                    154:   repository is very useful for people who read the pkgsrc-changes mailing
                    155:   list, so that they can make tactical decisions about when to upgrade
                    156:   the package.</p></li>
                    157: </ul></div>
                    158: <p>Please also recognize that, just because a new version of a package
                    159:   has been released, it should not automatically be upgraded in the CVS
                    160:   repository.  We prefer to be conservative in the packages that are
                    161:   included in pkgsrc - development or beta packages are not really the
                    162:   best thing for most places in which pkgsrc is used. Please use your
                    163:   judgement about what should go into pkgsrc, and bear in mind that
                    164:   stability is to be preferred above new and possibly untested features.</p>
                    165: </div>
                    166: <div class="sect1" lang="en">
                    167: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.7       snj       168: <a name="renaming-package"></a>21.6. Renaming a package in pkgsrc</h2></div></div></div>
                    169: <p>Renaming packages is not recommended.</p>
                    170: <p>When renaming packages, be sure to fix any references to old name
                    171:   in other Makefiles, options, buildlink files, etc.</p>
                    172: <p>Also When renaming a package, please define
                    173:   <code class="varname">SUPERSEDES</code> to the package name and dewey version
                    174:   pattern(s) of the previous package name.
                    175:   This may be repeated for multiple renames.
                    176:   The new package would be an exact replacement.
                    177: </p>
                    178: <p>Note that &#8220;<span class="quote">successor</span>&#8221; in the
                    179:   CHANGES-<em class="replaceable"><code>YYYY</code></em> file doesn't necessarily
                    180:   mean that it <span class="emphasis"><em>supersedes</em></span>, as that successor may
                    181:   not be an exact replacement but is a suggestion for the replaced
                    182:   functionality.</p>
                    183: </div>
                    184: <div class="sect1" lang="en">
                    185: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
                    186: <a name="moving-package"></a>21.7. Moving a package in pkgsrc</h2></div></div></div>
                    187: <p>It is preferred that packages are not renamed or moved, but if needed
                    188:   please follow these steps.
                    189: </p>
1.1       dsieger   190: <div class="orderedlist"><ol type="1">
                    191: <li><p>Make a copy of the directory somewhere else.</p></li>
                    192: <li>
                    193: <p>Remove all CVS dirs.</p>
                    194: <p>Alternatively to the first two steps you can also do:</p>
                    195: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cvs -d user@cvs.NetBSD.org:/cvsroot export -D today pkgsrc/category/package</code></strong></pre>
                    196: <p>and use that for further work.</p>
                    197: </li>
                    198: <li><p>Fix <code class="varname">CATEGORIES</code> and any
                    199: <code class="varname">DEPENDS</code> paths that just did &#8220;<span class="quote">../package</span>&#8221;
                    200: instead of &#8220;<span class="quote">../../category/package</span>&#8221;.</p></li>
1.7       snj       201: <li><p>In the modified package's Makefile, consider setting
                    202: <code class="varname">PREV_PKGPATH</code> to the previous category/package
                    203: pathname.  The <code class="varname">PREV_PKGPATH</code> can be used by tools
                    204: for doing an update using pkgsrc building; for example, it can
                    205: search the <a class="citerefentry" href="http://netbsd.gw.com/cgi-bin/man-cgi?pkg_summary+5+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">pkg_summary</span>(5)</span></a> database for <code class="varname">PREV_PKGPATH</code>
                    206: (if no <code class="varname">SUPERSEDES</code>) and then use the corresponding
                    207: new <code class="varname">PKGPATH</code> for that moved package.  Note that
                    208: it may have multiple matches, so the tool should also check on the
                    209: <code class="varname">PKGBASE</code> too.  The <code class="varname">PREV_PKGPATH</code>
                    210: probably has no value unless <code class="varname">SUPERSEDES</code> is not
                    211: set, i.e.  <code class="varname">PKGBASE</code> stays the same.  </p></li>
1.5       hubertf   212: <li><p><span class="command"><strong>cvs import</strong></span> the modified package in the new
1.1       dsieger   213: place.</p></li>
                    214: <li>
                    215: <p>Check if any package depends on it:
                    216: </p>
                    217: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cd /usr/pkgsrc</code></strong>
                    218: <code class="prompt">%</code> <strong class="userinput"><code>grep /package */*/Makefile* */*/buildlink*</code></strong></pre>
                    219: </li>
                    220: <li><p>Fix paths in packages from step 5 to point to new location.</p></li>
1.5       hubertf   221: <li><p><span class="command"><strong>cvs rm (-f)</strong></span> the package at the old location.</p></li>
1.1       dsieger   222: <li><p>Remove from <code class="filename">oldcategory/Makefile</code>.</p></li>
                    223: <li><p>Add to <code class="filename">newcategory/Makefile</code>.</p></li>
                    224: <li>
                    225: <p>Commit the changed and removed files:</p>
                    226: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile</code></strong></pre>
                    227: <p>(and any packages from step 5, of course).</p>
                    228: </li>
                    229: </ol></div>
                    230: </div>
                    231: </div>
                    232: <div class="navfooter">
                    233: <hr>
                    234: <table width="100%" summary="Navigation footer">
                    235: <tr>
                    236: <td width="40%" align="left">
                    237: <a accesskey="p" href="debug.html">Prev</a> </td>
                    238: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
                    239: <td width="40%" align="right"> <a accesskey="n" href="devfaq.html">Next</a>
                    240: </td>
                    241: </tr>
                    242: <tr>
1.4       rillig    243: <td width="40%" align="left" valign="top">Chapter 20. Debugging </td>
1.1       dsieger   244: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.4       rillig    245: <td width="40%" align="right" valign="top"> Chapter 22. Frequently Asked Questions</td>
1.1       dsieger   246: </tr>
                    247: </table>
                    248: </div>
                    249: </body>
                    250: </html>

CVSweb <webmaster@jp.NetBSD.org>