SelfProgrammingWiki: Cpw Tutorial

This tutorial is designed to show you how to use those features of C.P.W. which enable you to modify CPW's code.

It assumes that you know about wikis and the UsemodWiki conventions already. A general how-to-use-a-wiki page will be added later.

Please feel free to post questions onto these pages if anything is unclear.

Please note that we are in the middle of a name change (from SPW to CPW). So, some things are still "spw" (specifically, all of the actual program code uses "spw", as does much of the docs). Please pardon the confusion.

Introduction

CPW is a wiki written in Perl which allows arbitrary community members to make changes to the wiki engine code. CPW runs as the user "spw", and it "owns" the directory /spw. Accordingly, the community can modify anything under the /spw directory (but not most other parts of the filing system). See FilesysCommands for a list of commands which view or modify the filesystem.

The basic process for submitting a change to CPW's code is:

Download and prepare a local copy of CPW
Make your modifications to the code
Create a suitable patch file
Post your patch on the wiki (using the DoPatch command to indicate that it is not just conversation)
The patch will not be made until a peer review period has elapsed. During this period, any other user can veto the patch or extend the review period. After the peer review period (if no one has vetoed), CPW applies the patch.

All proposed changes to the code must be approved by the community. When you submit a change, there is a 4 day peer review period. During this period, anyone may effectively veto your change -- either because they don't like it, or just because they want more than 4 days to consider it. To "veto" a change, modify the page containing the change in any way -- this restarts the approval period. Note that any change may be re-vetoed indefinitely (even by a single person). If/when a 4-day period elapsed without any new vetos, the proposed patch is applied automatically by the CPW software.

Example of modifying the code of CPW

This example should only take a few minutes to work through. (please update this estimate if I'm wrong). This example was checked against a GNU/Linux system. Maybe it works for other systems, too (let us know).

Step #1: Download and prepare your copy of CPW

: cd /tmp wget -O spw.tar 'http://purl.net/net/cpw/spw.pl?action=download&path=\/spw\/spw.tar' tar -xovf spw.tar /tmp/spw/qsetup.pl
: While testing, remember that CPW currently does NOT work with mod_perl; under Apache, you may need to put an .htaccess file in /tmp or somewhere else with the line SetHandler cgi-scipt to turn off mod_perl.
: If you need more information on this step, please see MakingALocalCopyOfSpw.
: Some hints about running your own copy of CPW are at RunningALocalCopyOfSPW

Step #2: Make your modifications to the code

: cd /tmp/spw/bin cp /tmp/spw/bin/spw_main.pl /tmp/spw/bin/spw_main.pl.old
: Now make your desired changes to /tmp/spw/bin/spw_main.pl. For example, you might add in
: } elsif ($action eq "stupid") { &ReportError(Ts("I'm stupid"));
: to the long chain of elsifs in sub DoOtherRequest?. You should test and debug your changes on your own computer.

Step #3: Create a suitable patch file

: First, do this (diffs isn't a typo):
: ../diffs spw_main.pl.old spw_main.pl > my_patch
: This produces a unix patch file with absolute paths relative to CPW's base installation directory. For more information, see DiffsScript.

Step #4: Post your patch on the wiki

: Now, create a wiki page on CPW. Call it TestPatch. Put this in the editbox (it must be at the top, with nothing else before it):
: #DoPatch <nowiki><pre></pre></nowiki>
: Using a text editor, copy the contents of your patch file (my_patch in the example) and paste it into the wiki page, in between <pre> tags. You should have something a lot like

 #DoPatch

<pre>
*** /spw/bin/spw_main.pl.old	Mon May 12 23:50:15 2003
--- /spw/bin/spw_main.pl	Tue May 13 00:33:11 2003
***************
*** 2450,2453 ****
--- 2450,2455 ----
      } elsif ($action eq "showls") {
        &DoShowLs();
+     } elsif ($action eq "stupid") {
+       &ReportError(Ts("I'm stupid"));
      } else {
        # Later improve error reporting

</pre>

: If you need more information on this step, please see DoPatch.

Step #5: Wait

Now save the page and wait 4 days. If no one modifies the page TestPatch for 4 days (i.e. if there are no vetos), your patch will be applied. If this happens, RecentChanges? will show an entry like

: * (diff) TestPatch 6:58 am (65 changes) [EXECUTED PATCH COMMAND] . . . . . SPW

and the page TestPatch will be changed to show you the results of the patch; it will look something like:

#DidPatch?;

: Result:
: patching file /spw/bin/spw_main.pl

*** /spw/bin/spw_main.pl.old	Mon May 12 23:50:15 2003
--- /spw/bin/spw_main.pl	Tue May 13 00:33:11 2003
***************
*** 2450,2453 ****
--- 2450,2455 ----
      } elsif ($action eq "showls") {
        &DoShowLs();
+     } elsif ($action eq "stupid") {
+       &ReportError(Ts("I'm stupid"));
      } else {
        # Later improve error reporting

End of example

Other comments

Please be sure and read over other people's proposed changes to make sure they are good (and not hazardous to security). Be liberal in vetoing changes that you would like more time to read or think about.

That's all you need to get started. For example, with this method you should be able to take a patch from UseMod:WikiPatches? and apply it to spw_main.pl!

If you are interested in learning more about how CPW works, you might be interested in the other pages in CategoryOverview.

CategoryOverview

CategoryDocumentation

CpwTutorial