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
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
%authors;
]>
<article>
<artheader>
<title>New Committer Guide</title>
<authorgroup>
<author>
<surname>The FreeBSD Documentation Project</surname>
</author>
</authorgroup>
<pubdate>September 1999</pubdate>
<copyright>
<year>1999</year>
<holder>The FreeBSD Documentation Project</holder>
</copyright>
<abstract>
<para>Welcome, new committer, to the FreeBSD development
team!</para>
<para>The following docs are provided to orient you on doing CVS
operations on the FreeBSD central repository machine. A basic
familiarity with CVS is already assumed, although CVS
reference information, tutorials, and FAQs can also be found
at: <ulink url="http://www.cyclic.com/cyclic-pages/books.html">http://www.cyclic.com/cyclic-pages/books.html</ulink></para>
<para>Good luck, and welcome aboard!</para>
</abstract>
</artheader>
<sect1 id="admin">
<title>Administrative Details</title>
<informaltable frame="none" orient="port">
<tgroup cols="2">
<tbody>
<row>
<entry><emphasis>Main Repository Host</emphasis></entry>
<entry><hostid>freefall.FreeBSD.org</hostid></entry>
</row>
<row>
<entry>
<emphasis>International Crypto Repository Host</emphasis>
</entry>
<entry><hostid>internat.FreeBSD.org</hostid></entry>
</row>
<row>
<entry><emphasis>Login Methods</emphasis></entry>
<entry>&man.ssh.1;</entry>
</row>
<row>
<entry><emphasis>Main CVSROOT</emphasis></entry>
<entry>/home/ncvs</entry>
</row>
<row>
<entry><emphasis>International Crypto CVSROOT</emphasis></entry>
<entry>/home/cvs.crypt</entry>
</row>
<row>
<entry><emphasis>Main CVS Repository Meisters</emphasis></entry>
<entry>&a.jdp; and &a.peter; as well as &a.asami; for
<filename>ports/</filename></entry>
</row>
<row>
<entry>
<emphasis>International Crypto CVS Repository Meister</emphasis>
</entry>
<entry>&a.markm;</entry>
</row>
<row>
<entry><emphasis>Mailing List</emphasis></entry>
<entry><email>cvs-committers@FreeBSD.org</email>
[which you are now on]</entry>
</row>
<row>
<entry><emphasis>Mentor Name</emphasis></entry>
<entry>&a.jkh;</entry>
</row>
<row>
<entry><emphasis>Noteworthy CVS Tags</emphasis></entry>
<entry>RELENG_3 (3.x-STABLE), HEAD (-CURRENT)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>It is required that you use &man.ssh.1; or &man.telnet.1;
and Kerberos 5 to connect to the repository hosts. These are
generally more secure than plain &man.telnet.1; or
&man.rlogin.1; since credential negotiation will always be
encrypted. All traffic is encrypted by default with &man.ssh.1;.
With utilities like &man.ssh-agent.1; and &man.scp.1; also
available, &man.ssh.1; is also far more convenient. If you do
not know anything about &man.ssh.1, please see
<xref linkend="ssh.guide">.</para>
</sect1>
<sect1 id="cvs.operations">
<title>CVS Operations</title>
<para>CVS operations are usually done by logging into
<hostid>freefall</hostid>, making sure the
<envar>CVSROOT</envar> environment variable is set to
<filename>/home/ncvs</filename>, and then doing the appropriate
check-out/check-in operations. If you wish to add
something which is wholly new (like new ports, contrib-ified
sources, etc), a script called <quote>easy-import</quote> is
also provided for making the process easier. It automatically
adds the new module entry, does the appropriate thing with
<command>cvs import</command>, etc. – just run it without
arguments and it will prompt you for everything it needs to
know.</para>
<para>If you are familiar with remote CVS and consider yourself
pretty studly with CVS in general, you can also do CVS
operations directly from your own machine and local working
sources. Just remember to set <envar>CVS_RSH</envar> to
<wordasword>ssh</wordasword> so that you are using a relatively
secure and reliable transport. If you have no idea what any of
the above even means, on the other hand, then please stick with
logging into <hostid>freefall</hostid> and applying your diffs
with &man.patch.1;.</para>
<para>If you need to use CVS <command>add</command> and
<command>delete</command> operations in a manner that is
effectively a <quote>mv</quote> operation, then a repository
copy is in order rather than your CVS <command>add</command> and
<command>delete</command>. In a repository copy, a <link
linkend="conventions">CVS Meister</link> will copy the file(s)
to their new name and/or location and let you know when it is
done. The purpose of a repository copy is to preserve file
change history, or logs. We in the FreeBSD Project greatly
value the change history CVS gives to the project.</para>
</sect1>
<sect1 id="conventions">
<title>Conventions and Traditions</title>
<para>The CVS Repository Meisters (Peter Wemm and John Polstra)
are the <quote>owners</quote> of the CVS repository and
responsible for any and <emphasis>all</emphasis> direct
modification of it for the purposes of cleanup or fixing some
grievous abuse of CVS by a committer. No one else should
attempt to touch the repository directly. Should you cause some
repository accident, say a bad cvs import or tag operation, do
<emphasis role="bold">not</emphasis> attempt to fix it yourself!
Mail or call John or Peter immediately and report the problem to
one of them instead. The only ones allowed to directly fiddle
the repository bits are the repomeisters. Satoshi Asami is also a
repomeister for the <filename>ports/</filename> portion of the
tree. Mark Murray is the repomeister for the International
Crypto Repository in South Africa.</para>
<para>If you are a new committer, your very first commit should be
to add yourself to the developer's section (28.2) of the
Handbook. Figuring out how to check the handbook out and add an
entry for yourself is relatively easy but still remains a good
first test of your CVS skills. If you can handle that one,
you are probably going to be ok.</para>
<para>Your next step should be to introduce yourself to the other
committers, otherwise no one will have any idea who you are or
what you are working on. You do not have to write a comprehensive
biography, just write a paragraph or two about who you are and
what you plan to be working on as a committer in FreeBSD. Email
this to <email>cvs-committers@FreeBSD.org</email> and you will be on
your way!</para>
<para>Also, be sure to log into <hostid>hub.FreeBSD.org</hostid>
and create yourself a
<filename>/var/forward/<replaceable>user</replaceable></filename>
(where <replaceable>user</replaceable> is your username) file
which contains your principal e-mail address where you want mail
to <replaceable>yourusername</replaceable>@FreeBSD.org
to be forwarded. Really large mailboxes which have taken up
permanent residence on <hostid>hub</hostid> often get
<quote>accidently</quote> truncated without warning, so forward
it or read it and you will not lose it.</para>
<para>All new committers also have a mentor assigned to them for
the first few months. The name of your mentor listed at the top
of this message. Your mentor is more or less responsible for
explaining anything which is confusing to you and is also
responsible for your actions during this initial period. If you
make a bogus commit, it is only going to embarrass your mentor
and you should probably make it a policy to pass at least your
first few commits by your mentor before committing it to the
repository.</para>
<para>All commits should go to <literal>-CURRENT</literal> first
before being merged to <literal>-STABLE</literal>. No major new
features or high-risk modifications should be made to the
<literal>-STABLE</literal> branch.</para>
</sect1>
<sect1 id="developer.relations">
<title>Developer Relations</title>
<para>If you are working directly on your own code or on code
which is already well established as your responsibility, then
there is probably little need to check with other committers
before jumping in with a commit. If you see a bug in an area of
the system which is clearly orphaned (and there are a few such
areas, to our shame), the same applies. If, however, you are
about to modify something which is clearly being actively
maintained by someone else (and it is only by watching the
<literal>cvs-all</literal> mailing list that you can really get
a feel for just what is and is not) then consider sending the
change to them instead, just as you would have before becoming a
committer. For ports, you should contact the listed
<makevar>MAINTAINER</makevar> in the
<filename>Makefile</filename>. For other parts of the
repository, if you are unsure who the active maintainer might
be, it may help to scan the output of <command>cvs log</command>
to see who has committed changes in the past. If your queries go
unanswered or the committer otherwise indicates a lack of
proprietary interest in the area affected, go ahead and commit
it.</para>
<para>If you are at all unsure about a commit for any reason in
general, have it reviewed by <literal>-hackers</literal> first
before committing. Better to have it flamed then and there
rather than when it is part of the CVS repository. If you do
happen to commit something which results in controversy
erupting, you may also wish to consider backing the change out
again until the matter is settled. Remember – with CVS we
can always change it back.</para>
</sect1>
<sect1 id="gnats">
<title>GNATS</title>
<para>The FreeBSD Project utilizes
<application>GNATS</application> for tracking bugs and change
requests. Be sure that if you commit a fix or suggestion found
in a <application>GNATS</application> PR, you use
<command>edit-pr <replaceable>pr-number</replaceable></command>
on <hostid>freefall</hostid> to close it. It is also considered
nice if you take time to close any PRs associated with your
commits, if appropriate. Your can also make use of
&man.send-pr.1; yourself for proposing any change which you feel
should probably be made, pending a more extensive peer-review
first.</para>
<para>You can find out more about <application>GNATS</application>
at:</para>
<itemizedlist>
<listitem>
<para><ulink url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html">http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.FreeBSD.org/support.html">http://www.FreeBSD.org/support.html</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.FreeBSD.org/send-pr.html">http://www.FreeBSD.org/send-pr.html</ulink></para>
</listitem>
<listitem>
<para>&man.send-pr.1;</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="people">
<title>Who's Who</title>
<para>Besides Peter Wemm and John Polstra, the repository
meisters, there are other FreeBSD project members whom you will
probably get to know in your new role as a committer. Briefly,
and by no means all-inclusively, these are:</para>
<variablelist>
<varlistentry>
<term>&a.asami;</term>
<listitem>
<para>Is the portsmeister, meaning that he has ultimate
authority over any modifications to the ports collection or
ports make macro files. He is also the one responsible for
administering code freezes before the releases.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.bde;</term>
<listitem>
<para>Is Obersturmbahnfuhrer of the Style Police. When you
do a commit that could have been done better, Bruce will
be there to note it to you. Be thankful that someone
is.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.dg;</term>
<listitem>
<para>Is our principal architect and overseer of the VM
system. If you have a VM system change in mind,
coordinate it with David. Should you become locked in
bitter, intractable dispute with some other committer over
a proposed change (which does not happen very often,
thankfully) then an appeal to David to put on his P.A. hat
and make a final decision can also occasionally be
necessary.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.jkh;</term>
<listitem>
<para>Is the release engineer. He is responsible for
setting release deadlines and controlling the release
process. During code freezes, he also has final authority
on all changes to the system for whichever branch is
pending release status. If there is something you want
merged from <literal>-CURRENT</literal> to
<literal>-STABLE</literal> (whatever values those may have
at any given time), he is also the one to talk to about
it</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.markm;</term>
<listitem>
<para>Mark is the CVS repository meister for the
international cypto repository kept on
<hostid>internat.FreeBSD.org</hostid> in South Africa.</para>
<para>Mark also oversees most of the crypto code; if you have
any crypto updates, please ask Mark first.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.steve;</term>
<listitem>
<para>Steve is unofficial maintainer of
<filename>/usr/src/bin</filename>. If you have something
significant you'd like to do there, you should probably
coordinate it first with Steve. He's also Problem
Report-meister, along with &a.phk;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.brian;</term>
<listitem>
<para>Official maintainer of
<filename>/usr/bin/ppp</filename> and LPD.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.wollman;</term>
<listitem>
<para>If you need advice on obscure network internals or
aren't sure of some potential change to the networking
subsystem you have in mind, Garrett is someone to talk
to.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="ssh.guide">
<title>SSH Quick-Start Guide</title>
<procedure>
<step>
<para>Update and install the ssh port in
<filename>/usr/ports/security/ssh</filename> (should be
version 1.2.25 or later).</para>
</step>
<step>
<para>Make sure that you run &man.ssh-agent.1; before running
other applications. X users, for example, usually do this
from their <filename>.xsession</filename> or
<filename>.xinitrc</filename> file. See &man.ssh-agent.1;
for details.</para>
</step>
<step>
<para>Generate a key pair using &man.ssh-keygen.1;. The key
pair will wind up in the
<filename><envar>$HOME</envar>/.ssh</filename>
directory.</para>
</step>
<step>
<para>Copy your public key
(<filename><envar>$HOME</envar>/.ssh/identity.pub</filename>)
into your <filename>authorized_keys</filename> file in your
home directory on <hostid>freefall</hostid>
(i.e.
<filename><envar>$HOME</envar>/.ssh/authorized_keys</filename>).
</para>
</step>
</procedure>
<para>Now you should be able to use &man.ssh-add.1; for
authentication once per session. This will prompt you for
your private key's pass phrase, and then store it in your
authentication agent (&man.ssh-agent.1;) so that you won't
have to retype it over and over.</para>
<para>Test by doing something such as <command>ssh
freefall.FreeBSD.org ls /usr</command>.</para>
<para>For more information, see
<filename>/usr/ports/security/ssh</filename>, &man.ssh.1;,
&man.ssh-agent.1;, &man.scp.1;, and &man.ssh-keygen.1;.</para>
</sect1>
</article>
|