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

1.26      sevan       1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.1       dsieger     2: <html>
                      3: <head>
1.49    ! martin      4: <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        !             5: <title>Chapter 23. Submitting and Committing</title>
1.11      spz         6: <link rel="stylesheet" type="text/css" href="/global.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.49    ! martin      9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
        !            10: <link rel="prev" href="gnome.html" title="Chapter 22. GNOME packaging and porting">
        !            11: <link rel="next" href="policies.html" title="Chapter 24. pkgsrc Policies">
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.49    ! martin     16: <tr><th colspan="3" align="center">Chapter 23. Submitting and Committing</th></tr>
1.1       dsieger    17: <tr>
                     18: <td width="20%" align="left">
1.49    ! martin     19: <a accesskey="p" href="gnome.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="policies.html">Next</a>
1.1       dsieger    22: </td>
                     23: </tr>
                     24: </table>
                     25: <hr>
                     26: </div>
1.15      asau       27: <div class="chapter">
1.1       dsieger    28: <div class="titlepage"><div><div><h2 class="title">
1.49    ! martin     29: <a name="submit"></a>Chapter 23. Submitting and Committing</h2></div></div></div>
1.1       dsieger    30: <div class="toc">
                     31: <p><b>Table of Contents</b></p>
1.24      leot       32: <dl class="toc">
1.32      rillig     33: <dt><span class="sect1"><a href="submit.html#submitting-binary-packages">23.1. Submitting binary packages</a></span></dt>
                     34: <dt><span class="sect1"><a href="submit.html#submitting-your-package">23.2. Submitting source packages (for non-NetBSD-developers)</a></span></dt>
                     35: <dt><span class="sect1"><a href="submit.html#general-notes-for-changes">23.3. General notes when adding, updating, or removing packages</a></span></dt>
                     36: <dt><span class="sect1"><a href="submit.html#commit-messages">23.4. Commit Messages</a></span></dt>
                     37: <dt><span class="sect1"><a href="submit.html#committing-importing">23.5. Committing: Adding a package to CVS</a></span></dt>
                     38: <dt><span class="sect1"><a href="submit.html#updating-package">23.6. Updating a package to a newer version</a></span></dt>
                     39: <dt><span class="sect1"><a href="submit.html#renaming-package">23.7. Renaming a package in pkgsrc</a></span></dt>
                     40: <dt><span class="sect1"><a href="submit.html#moving-package">23.8. Moving a package in pkgsrc</a></span></dt>
1.1       dsieger    41: </dl>
                     42: </div>
1.15      asau       43: <div class="sect1">
1.1       dsieger    44: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.49    ! martin     45: <a name="submitting-binary-packages"></a>23.1. Submitting binary packages</h2></div></div></div>
1.1       dsieger    46: <p>Our policy is that we accept binaries only from pkgsrc
                     47:        developers to guarantee that the packages don't contain any
                     48:        trojan horses etc. This is not to annoy anyone but rather to
                     49:        protect our users! You're still free to put up your home-made
                     50:        binary packages and tell the world where to get them. NetBSD
                     51:        developers doing bulk builds and wanting to upload them please
1.49    ! martin     52:        see <a class="xref" href="bulk.html" title="Chapter 8. Creating binary packages for everything in pkgsrc (bulk builds)">Chapter 8, <i>Creating binary packages for everything in pkgsrc (bulk
1.16      asau       53: builds)</i></a>.</p>
1.1       dsieger    54: </div>
1.15      asau       55: <div class="sect1">
1.1       dsieger    56: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.49    ! martin     57: <a name="submitting-your-package"></a>23.2. Submitting source packages (for non-NetBSD-developers)</h2></div></div></div>
1.41      nia        58: <p>Firstly, you can import new packages into
1.49    ! martin     59:        pkgsrc-wip (<span class="quote">“<span class="quote">pkgsrc work-in-progress</span>”</span>); see the
1.41      nia        60:        homepage at <a class="ulink" href="https://pkgsrc.org/wip/" target="_top">https://pkgsrc.org/wip/</a>
                     61:        for details.</p>
                     62: <p>Next, check that your package is complete, compiles and
1.49    ! martin     63:        runs well; see <a class="xref" href="creating.html" title="Chapter 14. Creating a new pkgsrc package from scratch">Chapter 14, <i>Creating a new pkgsrc package from scratch</i></a> and the rest of this
1.41      nia        64:        document. Run the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkglint/index.html" target="_top"><code class="filename">pkgtools/pkglint</code></a>
                     65:        tool and fix any errors that appear.</p>
                     66: <p>Finally, send a report to the pkgsrc bug tracking system,
1.47      leot       67:        either with the <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/send-pr.1"><span class="citerefentry"><span class="refentrytitle">send-pr</span>(1)</span></a> command, or if you don't have
1.1       dsieger    68:        that, go to the web page
1.35      leot       69:        <a class="ulink" href="https://www.NetBSD.org/support/send-pr.html" target="_top">https://www.NetBSD.org/support/send-pr.html</a>,
1.8       snj        70:        which contains some instructions and a link to a form where you
                     71:        can submit packages.  The
1.40      leot       72:        <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/sysutils/gtk-send-pr/index.html" target="_top"><code class="filename">sysutils/gtk-send-pr</code></a> package is
1.8       snj        73:        also available as a substitute for either of the above two tools.
                     74:        </p>
1.1       dsieger    75: <p>In the form of the problem report, the category should be
1.49    ! martin     76:        <span class="quote">“<span class="quote">pkg</span>”</span>, the synopsis should include the package name
1.1       dsieger    77:        and version number, and the description field should contain a
                     78:        short description of your package (contents of the COMMENT
1.41      nia        79:        variable or DESCR file are OK).</p>
1.1       dsieger    80: </div>
1.15      asau       81: <div class="sect1">
1.1       dsieger    82: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.49    ! martin     83: <a name="general-notes-for-changes"></a>23.3. General notes when adding, updating, or removing packages</h2></div></div></div>
1.1       dsieger    84: <p>Please note all package additions, updates, moves, and
                     85:        removals in <code class="filename">pkgsrc/doc/CHANGES-<em class="replaceable"><code>YYYY</code></em></code>. It's very
                     86:        important to keep this file up to date and conforming to the
                     87:        existing format, because it will be used by scripts to
1.35      leot       88:        automatically update pages on <a class="ulink" href="https://www.NetBSD.org/" target="_top">www.NetBSD.org</a> and other
1.1       dsieger    89:        sites. Additionally, check the
                     90:        <code class="filename">pkgsrc/doc/TODO</code> file and remove the entry
                     91:        for the package you updated or removed, in case it was mentioned
                     92:        there.</p>
                     93: <p>When the <code class="varname">PKGREVISION</code> of a package is
                     94:        bumped, the change should appear in
                     95:        <code class="filename">pkgsrc/doc/CHANGES-<em class="replaceable"><code>YYYY</code></em></code> if it is security
                     96:        related or otherwise relevant. Mass bumps that result from a
                     97:        dependency being updated should not be mentioned. In all other
                     98:        cases it's the developer's decision.</p>
                     99: <p>There is a make target that helps in creating proper
1.5       hubertf   100:   <code class="filename">CHANGES-<em class="replaceable"><code>YYYY</code></em></code> entries:  <span class="command"><strong>make
1.1       dsieger   101:   changes-entry</strong></span>. It uses the optional <code class="varname">CTYPE</code>
                    102:   and <code class="varname">NETBSD_LOGIN_NAME</code> variables. The general
                    103:   usage is to first make sure that your <code class="filename">CHANGES-<em class="replaceable"><code>YYYY</code></em></code>
                    104:   file is up-to-date (to avoid having to resolve conflicts later-on)
1.5       hubertf   105:   and then to <span class="command"><strong>cd</strong></span> to the package directory.  For
                    106:   package updates, <span class="command"><strong>make changes-entry</strong></span> is enough.
1.1       dsieger   107:   For new packages, or package moves or removals, set the
                    108:   <code class="varname">CTYPE</code> variable on the command line to "Added",
                    109:   "Moved", or "Removed".  You can set <code class="varname">NETBSD_LOGIN_NAME</code>
1.5       hubertf   110:   in <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a> if your local login name is
1.9       jakllsch  111:   not the same as your NetBSD login name. The target also automatically
                    112:   removes possibly existing entries for the package in the
                    113:   <code class="filename">TODO</code> file. Don't forget to commit
1.16      asau      114:   the changes, e.g. by using <span class="command"><strong>make commit-changes-entry</strong></span>!
1.9       jakllsch  115:   If you are not using a checkout directly from cvs.NetBSD.org, but e.g.
                    116:   a local copy of the repository, you can set USE_NETBSD_REPO=yes. This
                    117:   makes the cvs commands use the main repository.
                    118:   </p>
1.1       dsieger   119: </div>
1.15      asau      120: <div class="sect1">
1.1       dsieger   121: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.49    ! martin    122: <a name="commit-messages"></a>23.4. Commit Messages</h2></div></div></div>
1.28      wiz       123: <p>For several years, there have been mirrors of pkgsrc in
1.46      jkoshy    124:   fossil, git, and hg. Standard practice when using these tools is to
1.28      wiz       125:   make the first line of a commit message function as a summary that
                    126:   can be read without the rest, such as is commonly done with "git log
                    127:   --oneline". For this reason, we have the following guidelines for
                    128:   pkgsrc commit messages:</p>
                    129: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
                    130: <li class="listitem"><p>Start the commit message with a line that explains the
1.29      wiz       131:     big picture in 65 characters or less. When a commit is for one
1.28      wiz       132:     package, include the name of the package. For updates, include the
                    133:     version to which it is updated.</p></li>
                    134: <li class="listitem"><p>Leave the next line empty.</p></li>
                    135: <li class="listitem"><p>Then come the details for the commit (changes in that
                    136:     package, reason for a change) and any relevant PRs. Wrap this
                    137:     section.</p></li>
                    138: </ul></div>
                    139: <p>Here is an example:
1.44      wiz       140: </p>
1.28      wiz       141: <pre class="programlisting">
1.44      wiz       142: libxslt: update to 1.0.30
1.28      wiz       143: 
1.44      wiz       144: Changes since 1.0.29:
                    145: ...
                    146: </pre>
1.28      wiz       147: <p>
                    148:   </p>
                    149: <p>Here is another example:
1.44      wiz       150: </p>
1.28      wiz       151: <pre class="programlisting">
1.44      wiz       152: mk/bsd.pkg.mk: enable SSP by default on NetBSD
1.28      wiz       153: 
1.44      wiz       154: (rationale)
                    155: </pre>
1.28      wiz       156: <p>
                    157:   </p>
1.49    ! martin    158: <p>Commit messages are final: no <span class="quote">“<span class="quote">cvs admin</span>”</span> is
1.28      wiz       159:   allowed on the pkgsrc repository to change commit messages.</p>
                    160: </div>
                    161: <div class="sect1">
                    162: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.49    ! martin    163: <a name="committing-importing"></a>23.5. Committing: Adding a package to CVS</h2></div></div></div>
1.1       dsieger   164: <p>This section is only of interest for pkgsrc developers with write
1.13      wiz       165:   access to the pkgsrc repository.</p>
1.49    ! martin    166: <p>When the package is finished, <span class="quote">“<span class="quote">cvs add</span>”</span> the files.
1.13      wiz       167: Start by adding the directory and then files in the directory. Don't
                    168: forget to add the new package to the category's
                    169: <code class="filename">Makefile</code>. Make sure you don't forget any files;
1.49    ! martin    170: you can check by running <span class="quote">“<span class="quote">cvs status</span>”</span>. An example:</p>
1.1       dsieger   171: <pre class="programlisting">
1.13      wiz       172: <code class="prompt">$</code> cd .../pkgsrc/category
                    173: <code class="prompt">$</code> cvs add pkgname
                    174: <code class="prompt">$</code> cd pkgname
                    175: <code class="prompt">$</code> cvs add DESCR Makefile PLIST distinfo buildlink3.mk patches
                    176: <code class="prompt">$</code> cvs add patches/p*
                    177: <code class="prompt">$</code> cvs status | less
1.14      wiz       178: <code class="prompt">$</code> cvs commit
1.13      wiz       179: <code class="prompt">$</code> cd ..
1.42      gutterid  180: <code class="prompt">$</code> vi Makefile # add SUBDIR+=pkgname line
1.14      wiz       181: <code class="prompt">$</code> cvs commit Makefile
1.16      asau      182: <code class="prompt">$</code> cd pkgname
1.17      jnemeth   183: <code class="prompt">$</code> make CTYPE=Added commit-changes-entry
1.1       dsieger   184: </pre>
                    185: <p>The commit message of the initial import should include part of the
                    186:   <code class="filename">DESCR</code> file, so people reading the mailing lists know
                    187:   what the package is/does.</p>
1.13      wiz       188: <p>Also mention the new package in
                    189: <code class="filename">pkgsrc/doc/CHANGES-20xx</code>.</p>
1.49    ! martin    190: <p>Previously, <span class="quote">“<span class="quote">cvs import</span>”</span> was suggested, but it was
        !           191: much easier to get wrong than <span class="quote">“<span class="quote">cvs add</span>”</span>.</p>
1.1       dsieger   192: </div>
1.15      asau      193: <div class="sect1">
1.1       dsieger   194: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.49    ! martin    195: <a name="updating-package"></a>23.6. Updating a package to a newer version</h2></div></div></div>
1.1       dsieger   196: <p>Please always put a concise, appropriate and relevant summary of the
                    197:   changes between old and new versions into the commit log when updating
                    198:   a package. There are various reasons for this:</p>
1.15      asau      199: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.10      wiz       200: <li class="listitem"><p>A URL is volatile, and can change over time. It may go away completely
1.1       dsieger   201:   or its information may be overwritten by newer information.</p></li>
1.10      wiz       202: <li class="listitem"><p>Having the change information between old and new versions in our CVS
1.1       dsieger   203:   repository is very useful for people who use either cvs or anoncvs.</p></li>
1.10      wiz       204: <li class="listitem"><p>Having the change information between old and new versions in our CVS
1.1       dsieger   205:   repository is very useful for people who read the pkgsrc-changes mailing
                    206:   list, so that they can make tactical decisions about when to upgrade
                    207:   the package.</p></li>
                    208: </ul></div>
                    209: <p>Please also recognize that, just because a new version of a package
                    210:   has been released, it should not automatically be upgraded in the CVS
                    211:   repository.  We prefer to be conservative in the packages that are
                    212:   included in pkgsrc - development or beta packages are not really the
                    213:   best thing for most places in which pkgsrc is used. Please use your
                    214:   judgement about what should go into pkgsrc, and bear in mind that
                    215:   stability is to be preferred above new and possibly untested features.</p>
                    216: </div>
1.15      asau      217: <div class="sect1">
1.1       dsieger   218: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.49    ! martin    219: <a name="renaming-package"></a>23.7. Renaming a package in pkgsrc</h2></div></div></div>
1.7       snj       220: <p>Renaming packages is not recommended.</p>
1.36      gutterid  221: <p>When renaming packages, be sure to fix any references to the old name
1.7       snj       222:   in other Makefiles, options, buildlink files, etc.</p>
1.34      leot      223: <p>
1.36      gutterid  224:   Also, when renaming a package, please add
1.34      leot      225:   the package name and version pattern(s) of the previous package
                    226:   to <code class="varname">SUPERSEDES</code>.
1.7       snj       227:   This may be repeated for multiple renames.
                    228:   The new package would be an exact replacement.
1.34      leot      229:   Example:
1.7       snj       230: </p>
1.34      leot      231: <pre class="programlisting">
                    232: SUPERSEDES+=    p5-IO-Compress-Zlib&lt;2.017
                    233: SUPERSEDES+=    optcomp-[0-9]*
                    234: </pre>
1.49    ! martin    235: <p>Note that <span class="quote">“<span class="quote">successor</span>”</span> in the
1.7       snj       236:   CHANGES-<em class="replaceable"><code>YYYY</code></em> file doesn't necessarily
                    237:   mean that it <span class="emphasis"><em>supersedes</em></span>, as that successor may
                    238:   not be an exact replacement but is a suggestion for the replaced
                    239:   functionality.</p>
                    240: </div>
1.15      asau      241: <div class="sect1">
1.7       snj       242: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.49    ! martin    243: <a name="moving-package"></a>23.8. Moving a package in pkgsrc</h2></div></div></div>
1.7       snj       244: <p>It is preferred that packages are not renamed or moved, but if needed
                    245:   please follow these steps.
                    246: </p>
1.10      wiz       247: <div class="orderedlist"><ol class="orderedlist" type="1">
                    248: <li class="listitem"><p>Make a copy of the directory somewhere else.</p></li>
                    249: <li class="listitem">
1.1       dsieger   250: <p>Remove all CVS dirs.</p>
                    251: <p>Alternatively to the first two steps you can also do:</p>
                    252: <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>
                    253: <p>and use that for further work.</p>
                    254: </li>
1.10      wiz       255: <li class="listitem"><p>Fix <code class="varname">CATEGORIES</code> and any
1.49    ! martin    256: <code class="varname">DEPENDS</code> paths that just did <span class="quote">“<span class="quote">../package</span>”</span>
        !           257: instead of <span class="quote">“<span class="quote">../../category/package</span>”</span>.</p></li>
1.10      wiz       258: <li class="listitem"><p>In the modified package's Makefile, consider setting
1.7       snj       259: <code class="varname">PREV_PKGPATH</code> to the previous category/package
                    260: pathname.  The <code class="varname">PREV_PKGPATH</code> can be used by tools
                    261: for doing an update using pkgsrc building; for example, it can
1.47      leot      262: search the <a class="citerefentry" href="//man.NetBSD.org/NetBSD-10.1/pkg_summary.5"><span class="citerefentry"><span class="refentrytitle">pkg_summary</span>(5)</span></a> database for <code class="varname">PREV_PKGPATH</code>
1.7       snj       263: (if no <code class="varname">SUPERSEDES</code>) and then use the corresponding
                    264: new <code class="varname">PKGPATH</code> for that moved package.  Note that
                    265: it may have multiple matches, so the tool should also check on the
                    266: <code class="varname">PKGBASE</code> too.  The <code class="varname">PREV_PKGPATH</code>
                    267: probably has no value unless <code class="varname">SUPERSEDES</code> is not
                    268: set, i.e.  <code class="varname">PKGBASE</code> stays the same.  </p></li>
1.43      gutterid  269: <li class="listitem"><p><span class="command"><strong>cvs add</strong></span> the modified package in the new
1.1       dsieger   270: place.</p></li>
1.10      wiz       271: <li class="listitem">
1.1       dsieger   272: <p>Check if any package depends on it:
                    273: </p>
                    274: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cd /usr/pkgsrc</code></strong>
                    275: <code class="prompt">%</code> <strong class="userinput"><code>grep /package */*/Makefile* */*/buildlink*</code></strong></pre>
                    276: </li>
1.10      wiz       277: <li class="listitem"><p>Fix paths in packages from step 5 to point to new location.</p></li>
                    278: <li class="listitem"><p><span class="command"><strong>cvs rm (-f)</strong></span> the package at the old location.</p></li>
                    279: <li class="listitem"><p>Remove from <code class="filename">oldcategory/Makefile</code>.</p></li>
                    280: <li class="listitem"><p>Add to <code class="filename">newcategory/Makefile</code>.</p></li>
                    281: <li class="listitem">
1.1       dsieger   282: <p>Commit the changed and removed files:</p>
                    283: <pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile</code></strong></pre>
                    284: <p>(and any packages from step 5, of course).</p>
                    285: </li>
                    286: </ol></div>
                    287: </div>
                    288: </div>
                    289: <div class="navfooter">
                    290: <hr>
                    291: <table width="100%" summary="Navigation footer">
                    292: <tr>
                    293: <td width="40%" align="left">
1.49    ! martin    294: <a accesskey="p" href="gnome.html">Prev</a> </td>
1.1       dsieger   295: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
1.49    ! martin    296: <td width="40%" align="right"> <a accesskey="n" href="policies.html">Next</a>
1.1       dsieger   297: </td>
                    298: </tr>
                    299: <tr>
1.49    ! martin    300: <td width="40%" align="left" valign="top">Chapter 22. GNOME packaging and porting </td>
1.1       dsieger   301: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.49    ! martin    302: <td width="40%" align="right" valign="top"> Chapter 24. pkgsrc Policies</td>
1.1       dsieger   303: </tr>
                    304: </table>
                    305: </div>
                    306: </body>
                    307: </html>

CVSweb <webmaster@jp.NetBSD.org>