SpwTutorial

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.

Introduction

SPW is a wiki written in Perl which allows arbitrary community members to make changes to the wiki engine code. SPW 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 SPW's code is:

1. Download and prepare a local copy of SPW
2. Make your modifications to the code
3. Create a suitable patch file
4. Post your patch on the wiki (using the DoPatch command to indicate that it is not just conversation)
5. 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), SPW 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 SPW software.

Example of modifying the code of SPW

Step #1: Download and prepare your copy of SPW

cd /tmp
wget -O spw.tar 'http://purl.net/net/spw/spw.pl?action=download&path=\/spw\/spw.tar'
tar -xovf spw.tar
/tmp/spw/qsetup.pl

While testing, remember that SPW 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 SPW 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 SPW's base installation directory. For more information, see DiffsScript.

Step #4: Post your patch on the wiki

Now, create a wiki page on SPW. Call it TestPatch. Put this in the editbox (it must be at the top, with nothing else before it):

 #DoPatch

<pre></pre>

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 SPW works, you might be interested in the other pages in CategoryOverview.

CategoryOverview

CategoryDocumentation