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

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

CVSweb <webmaster@jp.NetBSD.org>