3. Quick Start

In this chapter, we quickly setup the basic Patcher configuration for hacking on XEmacs. Adapt the example as you wish. Let's make some assumptions first:

• You own a computer.

• You have the `add-log' library from the `xemacs-base' package, version 1.48 or later, installed on your system.

• You're using XEmacs from the CVS repository.

• Your local copy of the repository is located in `/usr/local/src/XEmacs-21.5'.

• Your local copy of the repository is up-to-date, but you've done some hacking in the sources that you'd like to submit.

• Since you're lazy, you didn't write the ChangeLog entries yet.

3.1 Setting up Patcher

The first thing to do is to make patcher aware of your "XEmacs" project. Put this in your `.emacs' file:

(setq patcher-projects
      '(("XEmacs" "/usr/local/src/XEmacs-21.5"
         :to-address "xemacs-patches@xemacs.org")
        ))

As you can imagine, patcher-projects is a user option in which you store information about the projects you want to manage with Patcher. It is actually a list of what's called project descriptors. Here's the meaning of the only project descriptor we have in the example above: we have a project named "XEmacs", located in `/usr/local/src/XEmacs-21.5' and for which emails should be sent to xemacs-patches@xemacs.org.

Note the particular syntax for specifying the mailing address. This is what's called a project option. Contrary to the project's name and directory, which are mandatory and always appear as the first and second elements of a project descriptor, project options are optional and can appear in any order.

3.2 Calling Patcher

Now you want to build a patch with your changes, and prepare a message to submit them. The way Patcher works is currently to setup the message first, and then to control all subsequent operations from there. In other words, to create a patch, you actually ask Patcher to prepare a mail. Type this:

M-x patcher-mail

First, you're prompted (with completion) for a project name (the first element of each project descriptor, remember ?). We currently only have an "XEmacs" project, so hitting TAB will directly fill the minibuffer in with this only choice. Then, you're prompted for a subject line that will be used in the mail. Say something sensible.

Three operations are now executed in turn:

1. Patcher prepares a mail buffer. The message will be sent to the address you specified with the :to-address project option, and the subject line now reads "[PATCH] something sensible".

2. Patcher now builds the patch. The command used to do this is `cvs -q diff -u' (this is also a project option). Upon successful completion of this command (we assume that's indeed the case), the patch is inserted into the mail buffer. Some information about the patch is provided just above it (the command used, the files affected and so on).

3. Finally, Patcher generates ChangeLog skeletons from what it understands of the patch. This involves visiting the appropriate ChangeLog files, and creating initial entries.

3.3 Filling the ChangeLogs

Patcher has just created initial ChangeLog entries for you. You must now browse through the ChangeLog file(s) and fill the entries as you see fit. Once you're done, you can very well save the ChangeLog buffers. However, don't kill them ! Don't even think about it. Patcher still needs them. Now, please return to the mail buffer.

3.4 Filling the message

Now that you're satisfied with your ChangeLog entries and you've returned to the mail buffer, you want to write some explanation text in the message. I'll let you do that. You also want to insert the ChangeLog entries corresponding to your patch, since they are usually much more readable than the patch itself.

Inserting your ChangeLog entries in the mail buffer is as simple as typing `C-c C-p i'. This actually calls the function patcher-insert-change-logs, which places them just above the patch, with a short information line (per ChangeLog file) on top.

3.5 Committing the Patch

If you have commit access to your project, you should read this. Otherwise, you may directly see 3.6 Sending the Message.

Committing your changes involves three steps: preparing the commit command, preparing the commit log message, and actually committing the changes. Although Patcher can do all of this in one shot, it lets you control each step by default.

In order to start the commit process, simply type `C-c C-p c'. This calls the function patcher-commit-change. Congratulations. You've just been transported to a new buffer, the *Patcher Log Message* buffer. This buffer lets you edit the log message that will accompany your commit. Note that the message is initialized with the subject line of your mail. This is also a project option.

Once you're satisfied with the log message, type `C-c C-c'. This calls the function patcher-logmsg-commit, which computes the commit command to use. The command is displayed in a special buffer, the *Patcher Commit Command* buffer. The default commit command is `cvs commit', which of course is also a project option. Note that Patcher stores the log message in a temporary file and uses the `-F' cvs commit option. Finally, note that Patcher has automatically appended the affected ChangeLog files to the commit command.

At this point, you have the opportunity to abort the commit operation. Otherwise, answer positively and the commit will be executed. If you had not previously saved the ChangeLog files, Patcher will do it for you just before committing.

3.6 Sending the Message

Sending the message has actually nothing to do with Patcher. It depends on the method you use for sending mails, but will usually be done via a `C-c C-c' command of some sort. On thing to note however: if you've committed your changes via Patcher, the message has been slightly modified: the subject line now reads "[COMMIT] something sensible" instead of "[PATCH] ...", and a short commit notice has been inserted just at the beginning of the message's body.

That's it. That was easy. Congratulations on your first shot at Patcher, anyway ! Of course, Patcher is much more powerful and customizable than what has been described in this chapter. For a complete documentation on how to use and customize Patcher, please refer to 4. User Manual.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.