Annotation of htdocs/docs/pkgsrc/submit.html, revision 1.50
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.50 ! wiz 4: <meta charset="UTF-8">
1.49 martin 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<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>