docs/project/committer_guide.pod

   1 # Copyright (C) 2007-2008, Parrot 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; make codetest
  83
  84 Your Parrot working copy must C<make> successfully before
  85 committing your changes to the repository.
  86
  87 It would be best practice to run C<make test> and make sure that your change
  88 hasn't broken anything before committing.
  89 However, as C<make test> takes a long time, it is recommended to run at least
  90 C<make codetest>. This target runs only the file metadata and the
  91 basic coding standards tests.
  92
  93 In case you want to check the POD of your changed file, you can run
  94 C<perl t/doc/pod.t path/to/my/file >.
  95
  96 =head1 License
  97
  98 Each text file needs to have near its beginning the line (or equivalent
  99 depending upon the current language's comment character):
 100
 101   # Copyright (C) <creation_year>-<current_year>, Parrot Foundation.
 102
 103 =head1 Removing files
 104
 105 To remove a file from the Parrot source, you need to use the C<svn rm>
 106 command:
 107
 108   % svn rm <filename>
 109
 110 Also note that C<svn remove> and C<svn delete> do the same thing.
 111
 112 Removing files is much the same as adding files in that you need to run
 113 F<tools/dev/mk_manifest_and_skip.pl> to create the MANIFEST and
 114 MANIFEST.SKIP files appropriately.  Also, you should check that you've not
 115 broken anything by running C<make test> before committing the removal to the
 116 repository.
 117
 118 =head1 Branching and merging
 119
 120 To create a new branch from the parrot trunk you use the command:
 121
 122   % svn copy https://svn.parrot.org/parrot/trunk \
 123              https://svn.parrot.org/parrot/branches/<branch_name> \
 124                    -m "Creating a private branch of parrot/trunk."
 125
 126 where you might want to be a bit more informative in the commit message than
 127 that given here.  This copies the C<trunk> branch across to a new branch
 128 called C<branch_name> underneath the C<branches> subdirectory of the parrot
 129 repository.
 130
 131 =head2 Merging changes I<into> trunk
 132
 133 You first need to work out when the branch occurred.  This is done with
 134 C<svn log>:
 135
 136   % svn log -v --stop-on-copy https://svn.parrot.org/parrot/branches/<branch_name>
 137
 138 This will tell you the revision number when the branch happened.  You now
 139 need a clean working copy of C<trunk>, where you issue the command:
 140
 141   % svn merge -r<revision_number>:HEAD https://svn.parrot.org/parrot/branches/<branch_name>
 142
 143 Run C<svn status>, check the output of C<svn diff> to make sure things look
 144 sane, build parrot and run the test suite with C<make test> and if
 145 everything works, you can then commit this change to trunk.
 146
 147 =head2 Merging changes I<from> trunk
 148
 149 This works almost exactly the same as merging changes into trunk except it's
 150 in the opposite direction.  Now what you need is to work out when you
 151 branched from trunk (again with the help of C<svn log> and its
 152 C<--stop-on-copy> argument), having a clean working copy of your branch, and
 153 then running the command:
 154
 155   % svn merge -r<revision_number>:HEAD https://svn.parrot.org/parrot/trunk
 156
 157 Again, build and run the test suite to make sure everything worked (you
 158 might also have to resolve any conflicts) and then you can check in your
 159 change to the branch.
 160
 161 =head1 Rollbacks
 162
 163 It is sometimes necessary to undo a commit.  The best way to do this is with
 164 a working copy without local modifications, and then issue the command:
 165
 166   % svn merge -c <revision_number> https://svn.parrot.org/parrot/trunk
 167
 168 This merges I<out> the change which occurred in the C<trunk> branch at the
 169 revision C<revision_number>.  This command works with Subversion versions
 170 1.4 and above.  Below this version number, you'll need to use
 171
 172   % svn merge -r <revision_number>:<revision_number-1> https://svn.parrot.org/parrot/trunk
 173
 174 This merges the change in C<revision_number> I<backwards> so undoes it.
 175
 176 Note that these changes only occur in the current working copy.  To make the
 177 undo permanent, you need to commit the change in order for it to take
 178 effect.  This is, of course, (after making sure there aren't any conflicts,
 179 that C<svn diff> looks correct, and running the test suite to make
 180 B<absolutely sure> that nothing got broken in the process of undoing the
 181 change).
 182
 183 =head1 AUTHOR
 184
 185 Paul Cochrane <paultcochrane at gmail dot com>
 186
 187 =head1 SEE ALSO
 188
 189 F<docs/project/roles_responsibilities.pod>, F<RESPONSIBLE_PARTIES>
 190
 191 =cut