# Copyright (C) 2007-2008, Parrot Foundation.
# $Id: committer_guide.pod 36833 2009-02-17 20:09:26Z allison $

=head1 Committer Guide

From F<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.

=head1 Adding new files

To add a new file to Parrot, in your svn working copy use the command:

  % svn add <filename>

=head1 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.pl

=head1 svn 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 C<svn:eol-style>, C<svn:keywords> and
C<svn:mime-type> properties.

You can check the svn properties by running:

  % perl t/distro/file_metadata.t

=head2 C<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 C<svn:eol-style> set explicitly to
"LF".  These files are documented in F<t/distro/file_metadata.t>.  You set
their property appropriately by:

  % svn propset svn:eol-style LF <filename>

=head2 C<svn:mime-type>

For most files the C<svn:mime-type> property should be set correctly,
except for C<*.t> files which svn thinks they are troff files, so they need
their C<svn:mime-type> set explicitly to "text/plain":

  % svn propset svn:mime-type text/plain <filename>

=head2 C<svn:keywords>

All (text) files should have the C<svn:keywords> property set to
C<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 36833 2009-02-17 20:09:26Z allison $

(of course for C-language files you want to wrap this in C-style comments).

=head1 Ignored files

Files generated by Parrot at build time should get ignored such that
C<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
C<svn:ignore> property like so:

  $ svn propset svn:ignore <filename>

=head1 Tests before committing; make codetest

Your Parrot working copy must C<make> successfully before
committing your changes to the repository.

It would be best practice to run C<make test> and make sure that your change
hasn't broken anything before committing.
However, as C<make test> takes a long time, it is recommended to run at least
C<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
C<perl t/doc/pod.t path/to/my/file >.

=head1 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>, Parrot Foundation.

=head1 Removing files

To remove a file from the Parrot source, you need to use the C<svn rm>
command:

  % svn rm <filename>

Also note that C<svn remove> and C<svn delete> do the same thing.

Removing files is much the same as adding files in that you need to run
F<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 C<make test> before committing the removal to the
repository.

=head1 Branching and merging

To create a new branch from the parrot trunk you use the command:

  % svn copy https://svn.parrot.org/parrot/trunk \
             https://svn.parrot.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 C<trunk> branch across to a new branch
called C<branch_name> underneath the C<branches> subdirectory of the parrot
repository.

=head2 Merging changes I<into> trunk

You first need to work out when the branch occurred.  This is done with
C<svn log>:

  % svn log -v --stop-on-copy https://svn.parrot.org/parrot/branches/<branch_name>

This will tell you the revision number when the branch happened.  You now
need a clean working copy of C<trunk>, where you issue the command:

  % svn merge -r<revision_number>:HEAD https://svn.parrot.org/parrot/branches/<branch_name>

Run C<svn status>, check the output of C<svn diff> to make sure things look
sane, build parrot and run the test suite with C<make test> and if
everything works, you can then commit this change to trunk.

=head2 Merging changes I<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 C<svn log> and its
C<--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.parrot.org/parrot/trunk

Again, 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.

=head1 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.parrot.org/parrot/trunk

This merges I<out> the change which occurred in the C<trunk> branch at the
revision C<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.parrot.org/parrot/trunk

This merges the change in C<revision_number> I<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 C<svn diff> looks correct, and running the test suite to make
B<absolutely sure> that nothing got broken in the process of undoing the
change).

=head1 AUTHOR

Paul Cochrane <paultcochrane at gmail dot com>

=head1 SEE ALSO

F<docs/project/roles_responsibilities.pod>, F<RESPONSIBLE_PARTIES>

=cut