How to apply patches to PM code

Are you a god?
No.
Then... die!

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!)

Comment on How to apply patches to PM code

Replies are listed 'Best First'.
Re: How to apply patches to PM code by blakem (Monsignor) on Oct 02, 2002 at 07:55 UTC
Excellent documentation. What I'd really like to see is "How to test patches (a guide for pmdevils)" The only patches I've submitted are tiny one or two line changes, since I don't feel comfortable slinging more code than that around w/o a reasonable way to test it. Is there any way to test a patch other than installing a local copy of Everything2, or is the patching process mostly like coding in the dark? -Blake who should probably know better by now....	[reply]
(tye)Re: How to apply patches to PM code by tye (Sage) on Oct 02, 2002 at 16:14 UTC
It is mostly like coding in the dark¹. You should install your own copy of Everything. If mt2k can do it in one sitting (on Win32 even), then I bet you can too. We already have two central test environments. One allows new *.pm files to be tested without affecting the public access. The other does that plus also works on the backup database instead of the live database. It would be nice to add another database, backup all of the "code" and at least some of the "content" to it, but only copy volunteer users (mostly members of pmdev) and don't copy sensitive information (so, for example, you'd have a different password in this alternate database). Then most of the users could be made gods on this alternate system so that they could test code on it. Add to this a procedure for backing up the "code" from the live database to this new Olympus database (playground of the many gods), plus a feature to turn a node on the Olympus database into a patch on the live database, and we'd have a nice test environment. Unfortunately, we can't host this test system alongside the production system. Being able to create nodes in the Olympus system means that you can run any Perl code you like on that web server, which means you can work through any tricks we set up to try to hide the production DB password from you. Getting creative with security on the web server is probably not an option due to how the server is set up in order to make it easy for Pair to maintain it. And hosting it elsewhere adds lots of other problems to the mix. So feel free to find a place where you can set up Everything such that lots of pmdev members can use it for testing. Then you can use that to write and test the code for backing up PM code to Olympus and making PM patches from Olympus nodes. - tye (¹which just makes your screen easier to read)	[reply]
Re (2): How to apply patches to PM code by VSarkiss (Monsignor) on Oct 02, 2002 at 15:56 UTC
<aol> Me too! </aol> I very much second this. I often think I could contribute more if only I felt what I submitted would actually work. I have my own copy of E2, but that still isn't enough, because changes usually depend on other, existing, PM nodes. The other thing that stops me is that it's often necessary to patch two or three nodes at once (like the display page and the htmlcode behind it), and I'm not sure how to make a group of patches. A patchball, if you will. Is writing about it in the wiki enough? I'm still just an egg in so many ways...	[reply]
(tye)Re2: How to apply patches to PM code by tye (Sage) on Oct 02, 2002 at 18:35 UTC
I have my own copy of E2, but that still isn't enough, because changes usually depend on other, existing, PM nodes. ...which you have full access to the source of. If you want more than that, then you are in a great position to write such (for example, see my other reply). - tye (abusing PM for over 1/50th of a century)	[reply]
Re: How to apply patches to PM code by theorbtwo (Prior) on Oct 02, 2002 at 19:22 UTC
One minor change: in step two, if you give up on the patch as being too poorly written or not useful enough to be worth the effort, please tell the author about it, either via the pmdev wiki or by /msging the author (depending on if you feel like public humilition of the author and getting more people potentialy working on changes). I quite agree, BTW, about the problems of untestable code. The way I code requires lots of testing, both to verify exactly how things currently work, and to make sure the code I'm writing does what I think it does, so I end up trying to make very minimal changes to PM, or changes that are very localized. One thing that might be nice to get more pmdevils able to reasonably test is to set up a way to get the code of existing nodes en masse, or at least a little more easily -- AFAIK the best way to do it now is to view source and copy-and-paste out of the patching textbox. (I may hack up a little script to do this, or find a better way; I'm going to start on it now, and report back here when I'm done). Warning: Unless otherwise stated, code is untested. Do not use without understanding. Code is posted in the hopes it is useful, but without warranty. All copyrights are relinquished into the public domain unless otherwise stated. I am not an angel. I am capable of error, and err on a fairly regular basis. If I made a mistake, please let me know (such as by replying to this node).	[reply]

Back to Perl Monks Discussion