Committer Guide
From docs/roles_responsibilities.pod:
Contributors who submit numerous, high-quality patches may be considered
to become a Committer. Committers have commit access to the full Parrot
repository, but generally work only on one or more subprojects; Committer
categories are described below. Contributors may considered for commit
access either by being nominated by another Committer, or by asking for it.Adding new files
To add a new file to Parrot, in your svn working copy use the command:
% svn add <filename>MANIFEST
Be sure to update the MANIFEST when you've added new files. You do this by running:
% perl tools/dev/mk_manifest_and_skip.plsvn properties setting (file endings text/binary $Id: committer_guide.pod 19939 2007-07-17 20:52:55Z particle $)
New files also need to have the appropriate svn properties set. For most files this requires setting the svn:eol-style, svn:keywords and svn:mime-type properties.
svn:eol-style
Most files in Parrot should have the file endings set to "native". You do this like so:
% svn propset svn:eol-style=native <filename>Some files, however, require that the svn:eol-style set explicitly to "LF". These files are documented in t/distro/file_metadata.t. You set their property appropriately by:
% svn propset svn:eol-style=LF <filename>svn:mime-type
For most files the svn:mime-type property should be set correctly, except for *.t files which svn thinks they are troff files, so they need their svn:mime-type set explicitly to "text/plain":
% svn propset svn:mime-type=text/plain <filename>svn:keywords
All (text) files should have the svn:keywords property set to Author Date Id Revision. The command being:
% svn propset svn:keywords='Author Date Id Revision' <filename>Also, text files should have the following line somewhere near the beginning of the file (usually after the Copyright notice):
# $Id: committer_guide.pod 19939 2007-07-17 20:52:55Z particle $(of course for C-language files you want to wrap this in C-style comments).
Ignored files
Files generated by Parrot at build time should get ignored such that svn status doesn't pick them up. They also need to get added to MANIFEST.SKIP so that Parrot's configuration mechanism doesn't complain about extra files. You can tell svn to ignore files by setting the svn:ignore property like so:
$ svn propset svn:ignore <filename>Tests before committing; t/doc/pod.t
Your Parrot working copy should at least make before committing changes to the repository (people haven't checked for such things in the past, unfortunately, I think I'm one of them...). It would be best practice to run make test and make sure that your change hasn't broken anything before committing any changes. Your file should have some form of documentation, in most cases this will be pod. Hence, you should run t/doc/pod.t over the file to make sure that the pod is sane. If you choose the make test path this test should be taken care of for you.
License
Each text file needs to have near its beginning the line (or equivalent depending upon the current language's comment character):
# Copyright (C) <creation_year>-<current_year>, The Perl Foundation.Removing files
To remove a file from the Parrot source, you need to use the svn rm command:
% svn rm <filename>Also note that svn remove and svn delete do the same thing.
Removing files is much the same as adding files in that you need to run tools/dev/mk_manifest_and_skip.pl to create the MANIFEST and MANIFEST.SKIP files appropriately. Also, you should check that you've not broken anything by running make test before committing the removal to the repository.
Branching and merging
To create a new branch from the parrot trunk you use the command:
% svn copy https://svn.perl.org/parrot/trunk \
https://svn.perl.org/parrot/branches/<branch_name> \
-m "Creating a private branch of parrot/trunk."where you might want to be a bit more informative in the commit message than that given here. This copies the trunk branch across to a new branch called branch_name underneath the branches subdirectory of the parrot repository.
Merging changes into trunk
You first need to work out when the branch occurred. This is done with svn log:
% svn log -v --stop-on-copy https://svn.perl.org/parrot/branches/<branch_name>This will tell you the revision number when the branch happened. You now need a clean working copy of trunk, where you issue the command:
% svn merge -r<revision_number>:HEAD https://svn.perl.org/parrot/branches/<branch_name>Run svn status, check the output of svn diff to make sure things look sane, build parrot and run the test suite with make test and if everything works, you can then commit this change to trunk.
Merging changes from trunk
This works almost exactly the same as merging changes into trunk except it's in the opposite direction. Now what you need is to work out when you branched from trunk (again with the help of svn log and its --stop-on-copy argument), having a clean working copy of your branch, and then running the command:
% svn merge -r<revision_number>:HEAD https://svn.perl.org/parrot/trunkAgain, build and run the test suite to make sure everything worked (you might also have to resolve any conflicts) and then you can check in your change to the branch.
Rollbacks
It is sometimes necessary to undo a commit. The best way to do this is with a working copy without local modifications, and then issue the command:
% svn merge -c -<revision_number> https://svn.perl.org/parrot/trunkThis merges out the change which occurred in the trunk branch at the revision revision_number. This command works with Subversion versions 1.4 and above. Below this version number, you'll need to use
% svn merge -r <revision_number>:<revision_number-1> https://svn.perl.org/parrot/trunkThis merges the change in revision_number backwards so undoes it.
Note that these changes only occur in the current working copy. To make the undo permanent, you need to commit the change in order for it to take effect. This is, of course, (after making sure there aren't any conflicts, that svn diff looks correct, and running the test suite to make absolutely sure that nothing got broken in the process of undoing the change).
AUTHOR
Paul Cochrane <paultcochrane at gmail dot com>
SEE ALSO
docs/roles_responsibilities.pod, RESPONSIBLE_PARTIES