Add 'Fixing and Extending ComicPress'

Fixing-and-Extending-ComicPress.md

@@ -0,0 +1,72 @@
+h2. Where to do work on ComicPress
+
+Unless you already have the code written, <em>don't do development on your live site!</em> Install a test/local copy of WordPress and work on that. This is also the best approach to use when doing work on a new theme for your site ("Theme Tester":http://wordpress.org/extend/plugins/theme-tester/ or some equivalent is the next best).
+
+<notextile>
+<ul>
+<li>Windows: <a href="http://geeksaresexy.blogspot.com/2006/06/installing-wordpress-locally-under.html">http://geeksaresexy.blogspot.com/2006/06/installing-wordpress-locally-under.html</a></li>
+<li>Mac OS X: <a href="http://www.tech-recipes.com/rx/2764/leopard_install_local_wordpress_using_mamp/">http://www.tech-recipes.com/rx/2764/leopard_install_local_wordpress_using_mamp/</a></li>
+<li>Ubuntu w/ XAMPP for Linux: <a href="http://ubuntu.philipcasey.com/11/04/2009/xampp-and-wordpress-revisited/">http://ubuntu.philipcasey.com/11/04/2009/xampp-and-wordpress-revisited/</a></li>
+</ul>
+</notextile>
+
+Also, in your local PHP installation, get "XDebug":http://www.xdebug.org/ working. Its error messages are much more useful than the standard PHP ones, and "var_dump":http://us.php.net/manual/en/function.var-dump.php output looks nicer with it, too.
+
+h2. functions.php
+
+If you're not using the default ComicPress theme (say, you're using 3 column or GN), and you haven't customized your <code>functions.php</code> file, a new version of <code>functions.php</code> can (theoretically) be dropped into the target directory without affecting functionality.
+
+h2. Fixing Problems in ComicPress (in the base theme or your own theme)
+
+Fixing problems in ComicPress and WordPress gives you a good opportunity to learn "PHP":http://www.php.net/. If you've never done any development work before, it can be scary. There are people on the "forums":http://comicpress.org/forum/ that have good PHP skills. Ask there, please.
+
+* Before working on your files, <strong>make backups of everything!</strong> Database and theme files, please. Or, even better, use "git":http://git-scm.com/ to manage your work on the theme so that you can easily revert if you mess up.
+* Make sure error reporting is turned on. On production servers it often isn't (and it shouldn't be). At the top of your <code>functions.php</code> file, add <code>error_reporting(E_ALL)</code> while you're working on an issue, and then remove it when you're done.
+* Use "var_dump":http://us.php.net/manual/en/function.var-dump.php instead of "echo":http://www.php.net/echo to print out variable information.
+* Make sure your code is outputting what it really should be outputting by using View Source in your browser.
+* Learn to use "Firebug":http://www.getfirebug.com/ to diagnose display, tag, and network problems.
+** And, if you've got the skills, use "FirePHP":http://www.firephp.org/, too.
+* Look up what the WordPress function that you're trying to use actually does on one of the many PHPXref sites that have the WordPress code all processed. I recommend "http://phpxref.com/xref/wordpress/":http://phpxref.com/xref/wordpress/
+* If you really want to be thorough, set up unit tests for your new functionality using "PHPUnit":http://www.phpunit.de/ and "MockPress":https://github.com/johnbintz/mockpress/tree (or set up tests for an existing function!)
+
+h2. Producing a patch
+
+If you're using git, "git-format-patch":http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html will do the trick. Bundle up the patch and send it to me.
+
+If you're not using git, send along the modified theme files and I'll do my best to integrate your changes into the theme. Please be specific about what changed in your mail to me.
+
+h2. Documenting your work
+
+We use "PhpDocumentor":http://www.phpdoc.org/ and "PHPXref":http://phpxref.sourceforge.net/ to automatically generate documentation for the source code. If you're creating new functions or variables, use "JavaDoc-style":http://java.sun.com/j2se/javadoc/writingdoccomments/ comments in your code.
+
+Also, please don't do this:
+<pre>
+// this function does blah
+function my_new_function($param) {
+  // initialize blah
+  $param2 = magic($param);
+  // check the new param to see if it's a number
+  if (is_numeric($param2)) {
+    // make a new number
+    $param3 = more_magic($param2);
+    // print out the number
+    echo $param3;
+  // done
+  }
+// done
+}
+</pre>
+
+Instead, do this:
+
+<pre>
+/**
+ * Print out a magic number.
+ * @param string $initial_string The string we're passing in.
+ */
+function print_magic_number($initial_string) {
+  if (is_numeric($number_version = magic($initial_string))) {
+    echo more_magic($param3);
+  }
+}
+</pre>