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