Committer Guide
From docs/project/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, svn keywords)
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.
You can check the svn properties by running:
% perl t/distro/file_metadata.tsvn: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 29521 2008-07-16 14:57:41Z bernhard $(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; make codetest
Your Parrot working copy must make successfully before committing your changes to the repository.
It would be best practice to run make test and make sure that your change hasn't broken anything before committing. However, as make test takes a long time, it is recommended to run at least make codetest. This target runs only the file metadata and the basic coding standards tests.
In case you want to check the POD of your changed file, you can run perl t/doc/pod.t path/to/my/file .
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/project/roles_responsibilities.pod, RESPONSIBLE_PARTIES