|Welcome to the Monastery|
How to apply patches to PM codeby tye (Cardinal)
|on Oct 02, 2002 at 06:43 UTC||Need Help??|
Well, nothing so dramatic. Feel free to read (you might find it enlightening, amusing, depressing, or horrifying), but this probably doesn't apply to you. (:
How to apply patches to PM code (a guide for gods)
1) Obtain a patch (preferably by having someone else write it)
2) Inspect the patch. Click "View Code" to see the patch code instead of the "differences". Convince yourself it will work and is desirable. If not, edit the patch or make a new one (or give up).
3) Decide how much complaining you'll have to put up with if the patch doesn't work. Some examples, from worst to best: a) people might lose data, b) a popular feature will be unavailable, c) everyone will notice, d) many will notice, e) a fairly small subset of users will notice.
For (a), you really need to test the patch yourself before exposing it to the world. For example, if you are patching chatter features, then you could find some unused node of the same type as the node you want to patch (there will probably be quite a few). Rename it to something like "test X" where "X" is the name of the node you want to patch and cut'n'paste the patched code into the node.
For example, a patch to message (the opcode) could be done by turning some unused opcode node into "massage" and testing with http://perlmonks.org/?op=massage&... Usually, tho, you are patching "doFoo" which is used by "listBars" which is used by message (the opcode) and so you end up creating "dueFoo", then creating "lostBars" to use it, then creating "massage" to use that, creating just_chat to make it easy to use that, and finally testing your patch. (Of course, now you can't use just_chat for testing since it has finally been publically announced and so you'll have to create "unjust_chat", etc.)
When done testing, please try to remember to rename your test nodes to something that screams "UNUSED!" and make the code blank or nearly so.
For (e), you should probably just save yourself a lot of work and jump to the next step. For in-between cases, use your judgement. For example, you might choose to skip to the next step but do it during a "slow time" and announce that you are about to do it so that when "everyone notices" they aren't horribly surprised and only 4 or 5 of them will run off and post PM discussions, editor requests, "/msg gods", and/or e-mail vroom to report what they saw. :)
4) Prepare your escape route. First, look for easy escape routes. Click "related patches" and, with a little luck, you'll find your new patch at the top of the list and right after that will be the previously applied patch and clicking on it will show that the patch is "current". Leave a browser window (or tab) open on this previous patch that is "current". Then apply your new patch. If problems crop up, just apply that previous patch to undo your new patch.
If you aren't so lucky, you might have to search around to find the "current" patch. Worse, there may be no "current" patch. One way to go then is to simply create such a patch: Go to the node that was patched (using &displaytype=viewcode if the node type requires that), fill in a reasonable explanation (I like to find the closest patch, see what has changed since then and describe that here), and hit "submit" w/o changing any code. Verify that the new patch shows as "current" and then apply it (applying it doesn't change any code, it just sets the "last applied" date on the patch so that it will be sorted properly). Now you can do as outlined in the above paragraph.
A rare alternative is that you have a patch that is just trivially different from the current code. Then you might want to edit the patch to match the current code and use it as your "undo".
The last option is to bring up a browser window (or tab) on the node that is being patched, select "edit", and leave that there. Then apply the new patch. If a problem crops up, then you can return to this "edit" window and click "submit" to restore the old code.
5) Perhaps announce it. At least thank the author of the patch in the pmdev wiki. I usually wait for something particularly interesting or just an accumulation of several patches before posting a public node in announcement. People like to be informed about what is going on.
Note that this doesn't cover patching *.pm code. We should cover that at some point. I'm sure I've left parts out. Enjoy and good luck.
Minor updates applied- tye (now, everyone go practice!)