Added plugin writing guide.

NEWS

@@ -2,6 +2,8 @@ Leiningen NEWS -- history of user-visible changes
 
 = 1.2.0 / ???
 
+* Add plugin creation guide.
+
 * Include arglists in help output.
 
 * Make lein script usable from any subdirectory in the project root.

PLUGINS.md

@@ -0,0 +1,68 @@
+# Leiningen Plugins
+
+Leiningen tasks are simply functions in a leiningen.task namespace. So
+writing a Leiningen plugin is pretty straightforward; as long as it's
+available on the classpath, Leiningen will be able to use it.
+
+To use a plugin, add it to your project.clj :dev-dependencies and run
+"lein deps". Then you'll be able to invoke it with "lein my-plugin".
+
+## Writing a Plugin
+
+Start by generating a new project with "lein new myplugin", and add a
+leiningen.myplugin namespace with a myplugin function. That function
+should take at least one argument: the current project. The project is
+a map which is based on the project.clj file, but it also has :name,
+:group, :version, and :root keys added in. If you want it to take
+parameters from the command-line invocation, you can make it take more
+arguments.
+
+The docstring from the plugin's namespace will be displayed by the
+"lein help" task. The function's arglists will also be shown, so pick
+argument names that are clear and descriptive.
+
+## Leiningen 1.2
+
+The rest of this document only applies to Leiningen version 1.2+.
+
+If your task returns an integer, it will be used as the exit code for
+the process.
+
+You can set up aliases for your task by conjing a pair of strings with
+alias->task-name mappings on to the leiningen.core/aliases atom:
+
+    (swap! leiningen.core/aliases conj ["-v" "version"])
+
+## Hooks
+
+You can modify the behaviour of built-in tasks to a degree using
+hooks. Inspired by clojure.test's fixtures functionality, hooks are
+functions which wrap tasks and may alter their behaviour by using
+binding, altering the functions arguments or return value, only
+running the function conditionally, etc.
+
+    (defn skip-integration-hook [task]
+      (binding [clojure.test/test-var (test-var-skip :integration)]
+        (task)))
+
+    (add-hook 'test skip-integration-hook)
+
+The add-hook function takes a symbol for which task it's meant to
+apply to. You can also pass in :all to have it apply to every task.
+
+Hooks compose, so be aware that your hook may be running inside
+another hook. Hooks are loaded by looking for all namespaces under
+leiningen.hooks.* on the classpath and loading them in alphabetical
+order.
+
+Please add your plugins to [the list on the
+wiki](http://wiki.github.com/technomancy/leiningen/plugins).
+
+If you want to call another task from a plugin, don't call it
+directly. Call it with leiningen.core/run-task instead so it will load
+all its hooks and run the task wrapped inside them.
+
+## Have Fun
+
+Hopefully the plugin mechanism is simple and flexible enough to let
+you bend Leiningen to your will.

project.clj

@@ -10,6 +10,5 @@
                  [ant/ant "1.6.5"]
                  [jline "0.9.94"]
                  [org.apache.maven/maven-ant-tasks "2.0.10"]]
-  :dev-dependencies [[swank-clojure "1.2.1"]
+  :dev-dependencies [[swank-clojure "1.2.1"]]
-                     [autodoc "0.7.0"]]
   :main leiningen.core)

todo.org

@@ -18,8 +18,11 @@ Leiningen TODOs
 ** DONE upgrade task (patch submitted)
 ** DONE doc generation (autodoc plugin)
 * For 1.2.0
-** TODO document plugin creation
+** TODO include lib/dev in find-lib-jars
-** TODO document all known project.clj keys
+** TODO document version ranges
+** TODO document checkout dependencies
+** DONE document plugin creation
+** DONE document all known project.clj keys
 ** DONE disable frickin [null] logging from ant (come on srsly)
 ** DONE recover from missing test exit map gracefully
 ** DONE Help task should display arglist
@@ -35,6 +38,7 @@ Leiningen TODOs
 ** DONE classpath task to just print configured classpath
 ** DONE move repl task from shell script to clojure code
 * For later
+** TODO test classification using metadata; run a subset of tests
 ** TODO bin script has stabilized; self-install for dev versions should work
 ** TODO differentiate between ns-level/fn-level help docstrings
 ** TODO a list of dirs to include in the jar when building