handy hint: getting a perforce change as a usable patch

[p5sagit/p5-mst-13.2.git] / Porting / repository.pod

diff --git a/Porting/repository.pod b/Porting/repository.pod
index 54960bf..9b59bba 100644 (file)
--- a/Porting/repository.pod
+++ b/Porting/repository.pod
@@ -2,8 +2,16 @@
 
 repository - Using the Perl repository
 
-This document describes what a Perl Porter needs to do
-to start using the Perl repository.
+=head1 Synopsis
+
+First, we assume here that you have already decided that you will
+need B<write> access to the repository.  If all you need is B<read>
+access, there are much better ways to access the most current state of
+the perl repository, or explore individual files and patches therein.
+See L<perlhack> for details.
+
+This document describes what a Perl Porter needs to do to start using
+the Perl repository.
 
 =head1 Prerequisites
 
@@ -83,8 +91,7 @@ TCP "tunnel" rather than by using ssh to login to or invoke any
 ordinary commands on the repository. When you want to start a
 session using the repository, use the command
 
-    ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com 
-foo
+    ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com foo
 
 If you are not using the default filename of F<~/.ssh/identity>
 to hold your perl repository private key then you'll need to add
@@ -100,10 +107,10 @@ describe what all those ssh arguments are for.
 
 =over 4
 
-=item B<-l perl>
+=item B<-l perlrep>
 
-Use a remote username of perl. The account on the repository which
-provides the end-point of the ssh tunnel is named "perl".
+Use a remote username of perlrep. (The account on the repository which
+provides the end-point of the ssh tunnel is named "perlrep".)
 
 =item B<-f>
 
@@ -145,8 +152,8 @@ be used for the value of the P4PORT environment variable (q.v.).
 
 =item sickle.activestate.com
 
-This is the canonical IP name of the host on which the perl
-repository runs. Its IP number is 199.60.48.20.
+This is the canonical name of the host on which the perl repository
+resides.
 
 =item foo
 
@@ -192,7 +199,7 @@ the section above on the B<-L 1666:127.0.0.1:1666> option to ssh.
 
 The value of this is the name by which Perforce knows your
 host's workspace. You need to pick a name (normally, your
-Perforce username, a dash, and your hostname)
+Perforce username, a dash, and your host's short name)
 when you first start using the perl repository and then
 stick with it.
 
@@ -251,9 +258,10 @@ The C<p4 users> command lists all currently known users.
 Once these three environment variables are set, you can use the
 perforce p4 client exactly as described in its documentation.
 After setting these variables and connecting to the repository
-for the first time, you should use the C<p4 user> and
-C<p4 client> commands to tell perforce the details of your
-new username and your new client workspace specifications.
+for the first time, you should use the C<p4 user> command to
+set a valid email address for yourself.  Also use the C<p4 client>
+command to specify your workspace specifications for each
+individual client from which you will interact with the repository.
 
 =head1 Ending a Repository Session
 
@@ -329,9 +337,9 @@ back into the mainline, they do:
 
 Generating a patch for change#42 is done as follows:
 
-    % p4 describe -du 42 | p4desc | p4d2p > change-42.patch
+    % p4genpatch 42 > change-42.patch
 
-F<p4desc> and F<>p4d2p> are to be found in //depot/perl/Porting/.
+F<p4genpatch> is to be found in //depot/perl/Porting/.
 
 The usual routine to apply a patch is
 
@@ -357,7 +365,10 @@ Other useful Perforce commands
     % p4 describe -du 12345 # show change 12345
 
 Note: the output of "p4 describe" is not in proper diff format, use
-the F<Porting/p4d2p> to convert.
+the F<Porting/p4genpatch> to get a diff-compatible format.
+(Note that it may be easier to get one already prepared: grep
+L<perlhack> for APC, and append eg "/diffs/12345.gz" to one of the
+URLs to get a usable patch.)
 
     % p4 diff -se ./...     # have I modified something but forgotten
                             # to "p4 edit", easy faux pas with autogenerated
@@ -406,5 +417,3 @@ More updates by Jarkko Hietaniemi, jhi@iki.fi, 28 June 2001.
 Perforce clarifications by Randall Gellens, rcg@users.sourceforge.net, 12 July 2001.
 
 =cut
-
-