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