Patch submission

Parrot development proceeds through a continuous stream of patches. Patches are the currency of exchange in the project--the unit of work. Patches can fix bugs, add features, modify capabilities, remove cruft, and improve the suite of tests and the project documentation. If something needs to change, it will typically require the submission of a new patch.

While anyone is free to submit a patch, only a small number of people have the ability to apply patches to the central Parrot repository. These people are called committers. By allowing all people to get involved through patch submission and testing, the project can harness the efforts of a large group but still keep the same high quality as a small group of experienced developers.

Every submitted patch is automatically forwarded to the p2 list where it's subject to peer review. Small patches typically spark little debate, and can be well-tested on many platforms before being committed to the repository. Patches tend to be small modular changes, which makes for easy testing and evaluation. Occasionally a large feature such as an entire language implementation is submitted in a single patch, but these are the exceptions.

Submitting a patch is fairly straightforward. You create a file that lists all your changes, a diff or a patch, and email it to the ticket tracking system at parrotbug@parrotcode.org. It's important to make sure your patch and your email have descriptive titles so that the committers and testers have a better idea about what it does. The body of your email should also include a good description about what you changed and why.

It's important that you create your patches from the Parrot git repository, not from a tarball or a snapshot. This way, you can ensure that your diff is made against the latest version of the files. If you patch an old version, the problem may have already been resolved! Make sure the paths listed in the patch match those in the repository. There are two methods of creating patches that will do this for you. You can make changes directly in your clone of the git repository and then create diffs using the command git diff. Alternatively, you can make a copy of the repository and then create diffs between the two copies with the diff -u command:

  diff -u parrot/README.pod parrot_changed/README.pod

Either method is fine, and both are equally common on p2. Your working style and the types of changes you make--small and modular versus large and sweeping--will influence which method you choose.

Next, when you're making changes, take some extra time to consider how your patch affects the rest of the system. If your patch adds a new file, patch the main MANIFEST file to include it. If you add a new feature, make sure to write tests for it. If you fix a bug, add a test to prove that it's fixed. See "Writing Tests" in Chapter 9 for more on writing tests for Parrot. Tests are very important for Parrot development, and writing good tests is a valuable skill for developers to have. Before you submit a patch always recompile the system yourself with the patch included and run all tests to prove that it works. You can build and test Parrot completely by running the following commands:

  make clean
  perl Configure.pl
  make
  make test

Consider the people who will review and apply your patch, and try to make their jobs easier. Patch filenames should be as descriptive as possible: fix_readme_aardvark_typo.patch is far better than README.patch. An attached file is better than a diff pasted into an email, because it can be applied without manual editing. The conventional extension for patch files is .patch.

In the email message, always start the subject with "[PATCH]", and make the subject as clear as possible: "[PATCH] misspelled aardvark in main README.pod file" is better than "[PATCH] typo". The body of the message should clearly explain what the patch is supposed to do and why you're submitting it. Make a note if you're adding or deleting files so they won't be missed.

Here is a good example of a patch submission using the git diff method (an actual patch from p2). It's short, sticks to the point, and clearly expresses the problem and the solution. The patch filename and the subject of the message are both descriptive:

Possible alternates: ticket #23501, #24053 (not from top level)

  Subject: [PATCH] Pointers in List_chunk not initialized
  From: Bruce Gray
  
  On Win32, these tests are segfaulting due to invalid
  pointers in List_chunk structs:
  t/op/string.t             97-98
  t/pmc/intlist.t           3-4
  t/pmc/pmc.t               80
  
  The problem is caused by list.c/allocate_chunk not
  initializing the pointers. This patch corrects the problem.
  
  --
  Hope this helps,
  Bruce Gray

With the attached file list_chunk_initialize.patch:

  Index: list.c
  =========================================
  RCS file: /cvs/public/parrot/list.c,v
  retrieving revision 1.23
  diff -u -r1.23 list.c
  --- list.c        27 Dec 2002 09:33:11 -0000        1.23
  +++ list.c        28 Dec 2002 03:37:35 -0000
  @@ -187,6 +187,10 @@
       Parrot_block_GC_sweep(interpreter);
       chunk = (List_chunk *)new_bufferlike_header(interpreter, sizeof(*chunk));
       chunk->items = items;
  +    chunk->n_chunks = 0;
  +    chunk->n_items  = 0;
  +    chunk->next     = NULL;
  +    chunk->prev     = NULL;
       Parrot_allocate_zeroed(interpreter, (Buffer *)chunk, size);
       Parrot_unblock_GC_mark(interpreter);
       Parrot_unblock_GC_sweep(interpreter);