docs/project/committer_guide.pod

   1 # Copyright (C) 2007, The Perl Foundation.
   2 # $Id$
   3
   4 =head1 Committer Guide
   5
   6 From F<docs/project/roles_responsibilities.pod>:
   7
   8   Contributors who submit numerous, high-quality patches may be considered
   9   to become a Committer. Committers have commit access to the full Parrot
  10   repository, but generally work only on one or more subprojects; Committer
  11   categories are described below. Contributors may considered for commit
  12   access either by being nominated by another Committer, or by asking for it.
  13
  14 =head1 Adding new files
  15
  16 To add a new file to Parrot, in your svn working copy use the command:
  17
  18   % svn add <filename>
  19
  20 =head1 MANIFEST
  21
  22 Be sure to update the MANIFEST when you've added new files.  You do this
  23 by running:
  24
  25   % perl tools/dev/mk_manifest_and_skip.pl
  26
  27 =head1 svn properties setting (file endings, text/binary, svn keywords)
  28
  29 New files also need to have the appropriate svn properties set.  For most
  30 files this requires setting the C<svn:eol-style>, C<svn:keywords> and
  31 C<svn:mime-type> properties.
  32
  33 You can check the svn properties by running:
  34
  35   % perl t/distro/file_metadata.t
  36
  37 =head2 C<svn:eol-style>
  38
  39 Most files in Parrot should have the file endings set to "native".  You do
  40 this like so:
  41
  42   % svn propset svn:eol-style native <filename>
  43
  44 Some files, however, require that the C<svn:eol-style> set explicitly to
  45 "LF".  These files are documented in F<t/distro/file_metadata.t>.  You set
  46 their property appropriately by:
  47
  48   % svn propset svn:eol-style LF <filename>
  49
  50 =head2 C<svn:mime-type>
  51
  52 For most files the C<svn:mime-type> property should be set correctly,
  53 except for C<*.t> files which svn thinks they are troff files, so they need
  54 their C<svn:mime-type> set explicitly to "text/plain":
  55
  56   % svn propset svn:mime-type text/plain <filename>
  57
  58 =head2 C<svn:keywords>
  59
  60 All (text) files should have the C<svn:keywords> property set to
  61 C<Author Date Id Revision>.  The command being:
  62
  63   % svn propset svn:keywords 'Author Date Id Revision' <filename>
  64
  65 Also, text files should have the following line somewhere near the beginning
  66 of the file (usually after the Copyright notice):
  67
  68   # $Id$
  69
  70 (of course for C-language files you want to wrap this in C-style comments).
  71
  72 =head1 Ignored files
  73
  74 Files generated by Parrot at build time should get ignored such that
  75 C<svn status> doesn't pick them up.  They also need to get added to
  76 MANIFEST.SKIP so that Parrot's configuration mechanism doesn't complain
  77 about extra files.  You can tell svn to ignore files by setting the
  78 C<svn:ignore> property like so:
  79
  80   $ svn propset svn:ignore <filename>
  81
  82 =head1 Tests before committing; t/doc/pod.t
  83
  84 Your Parrot working copy should B<at least> C<make> before committing changes
  85 to the repository (people haven't checked for such things in the past,
  86 unfortunately, I think I'm one of them...).  It would be best practice to
  87 run C<make test> and make sure that your change hasn't broken anything
  88 before committing any changes.  Your file should have some form of
  89 documentation, in most cases this will be pod.  Hence, you should run
  90 F<t/doc/pod.t> over the file to make sure that the pod is sane.  If you
  91 choose the C<make test> path this test should be taken care of for you.
  92
  93 =head1 License
  94
  95 Each text file needs to have near its beginning the line (or equivalent
  96 depending upon the current language's comment character):
  97
  98   # Copyright (C) <creation_year>-<current_year>, The Perl Foundation.
  99
 100 =head1 Removing files
 101
 102 To remove a file from the Parrot source, you need to use the C<svn rm>
 103 command:
 104
 105   % svn rm <filename>
 106
 107 Also note that C<svn remove> and C<svn delete> do the same thing.
 108
 109 Removing files is much the same as adding files in that you need to run
 110 F<tools/dev/mk_manifest_and_skip.pl> to create the MANIFEST and
 111 MANIFEST.SKIP files appropriately.  Also, you should check that you've not
 112 broken anything by running C<make test> before committing the removal to the
 113 repository.
 114
 115 =head1 Branching and merging
 116
 117 To create a new branch from the parrot trunk you use the command:
 118
 119   % svn copy https://svn.perl.org/parrot/trunk \
 120              https://svn.perl.org/parrot/branches/<branch_name> \
 121                    -m "Creating a private branch of parrot/trunk."
 122
 123 where you might want to be a bit more informative in the commit message than
 124 that given here.  This copies the C<trunk> branch across to a new branch
 125 called C<branch_name> underneath the C<branches> subdirectory of the parrot
 126 repository.
 127
 128 =head2 Merging changes I<into> trunk
 129
 130 You first need to work out when the branch occurred.  This is done with
 131 C<svn log>:
 132
 133   % svn log -v --stop-on-copy https://svn.perl.org/parrot/branches/<branch_name>
 134
 135 This will tell you the revision number when the branch happened.  You now
 136 need a clean working copy of C<trunk>, where you issue the command:
 137
 138   % svn merge -r<revision_number>:HEAD https://svn.perl.org/parrot/branches/<branch_name>
 139
 140 Run C<svn status>, check the output of C<svn diff> to make sure things look
 141 sane, build parrot and run the test suite with C<make test> and if
 142 everything works, you can then commit this change to trunk.
 143
 144 =head2 Merging changes I<from> trunk
 145
 146 This works almost exactly the same as merging changes into trunk except it's
 147 in the opposite direction.  Now what you need is to work out when you
 148 branched from trunk (again with the help of C<svn log> and its
 149 C<--stop-on-copy> argument), having a clean working copy of your branch, and
 150 then running the command:
 151
 152   % svn merge -r<revision_number>:HEAD https://svn.perl.org/parrot/trunk
 153
 154 Again, build and run the test suite to make sure everything worked (you
 155 might also have to resolve any conflicts) and then you can check in your
 156 change to the branch.
 157
 158 =head1 Rollbacks
 159
 160 It is sometimes necessary to undo a commit.  The best way to do this is with
 161 a working copy without local modifications, and then issue the command:
 162
 163   % svn merge -c <revision_number> https://svn.perl.org/parrot/trunk
 164
 165 This merges I<out> the change which occurred in the C<trunk> branch at the
 166 revision C<revision_number>.  This command works with Subversion versions
 167 1.4 and above.  Below this version number, you'll need to use
 168
 169   % svn merge -r <revision_number>:<revision_number-1> https://svn.perl.org/parrot/trunk
 170
 171 This merges the change in C<revision_number> I<backwards> so undoes it.
 172
 173 Note that these changes only occur in the current working copy.  To make the
 174 undo permanent, you need to commit the change in order for it to take
 175 effect.  This is, of course, (after making sure there aren't any conflicts,
 176 that C<svn diff> looks correct, and running the test suite to make
 177 B<absolutely sure> that nothing got broken in the process of undoing the
 178 change).
 179
 180 =head1 AUTHOR
 181
 182 Paul Cochrane <paultcochrane at gmail dot com>
 183
 184 =head1 SEE ALSO
 185
 186 F<docs/project/roles_responsibilities.pod>, F<RESPONSIBLE_PARTIES>
 187
 188 =cut