From 1bff678cbff039deab93edf2970f443c18e9bb76 Mon Sep 17 00:00:00 2001
From: Ivy Foster <address@hidden>
Date: Fri, 9 May 2008 17:24:19 -0400
Subject: [PATCH] Added HACKING section to the manual.

---
 stumpwm.texi.in |  283 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 283 insertions(+), 0 deletions(-)

diff --git a/stumpwm.texi.in b/stumpwm.texi.in
index 67b413c..5603514 100644
--- a/stumpwm.texi.in
+++ b/stumpwm.texi.in
@@ -91,6 +91,7 @@ This document explains how to use The Stump Window Manager.
 * Interacting With X11::        
 * Miscellaneous Commands::      
 * Hooks::                       
+* Hacking::
 * Command and Function Index::  
 * Variable Index::              
 
@@ -139,6 +140,11 @@ Miscellaneous Commands
 * Timers::                      
 * Getting Help::                
 
+Hacking
+
+* General Advice::
+* Using git with StumpWM::
+
 @end detailmenu
 @end menu
 
@@ -1072,6 +1078,283 @@ $$$ *key-press-hook*
 $$$ *root-click-hook*
 $$$ *mode-line-click-hook*
 
address@hidden Hacking, Command and Function Index, Hooks, Top
address@hidden Hacking
+
+For those of you who have worked on Free Software projects before,
+this part should probably be fairly intuitive.
+
address@hidden
+* General Advice::
+* Using git with StumpWM::
address@hidden menu
+
address@hidden General Advice, Using git with StumpWM, , Hacking
address@hidden Hacking:  General Advice
+
address@hidden
+
address@hidden
+Pay attention to file names and contents. If you're making changes to
+mode-line related code, don't put it in core.lisp. If you're
+introducing some completely new featureset, consider putting all of
+the new code in a new file.
+
address@hidden
+Does a command need to be user-visible ("interactive") or is it just
+called by other commands?
+
address@hidden
address@hidden
+If it's not going to be user-visible, you can just use the familiar
+(defun foo ()...) syntax.
+
address@hidden
+If you want the command to be used interactively, you use StumpWM's
+defcommand syntax, as in the examples below.
+
address@hidden
+    (defcommand test (foo bar)
+       ((:string "How you're going to prompt for variable foo: ")
+        (:number "How you want to prompt for variable bar: "))
+       "This command is a test"
+       (body...))
+
+    (defcommand test2 () ()
+       "This is also a test"
+       (body...))
+
+    (defcommand title (args) (interactive-args)
+       "Doc string"
+       (body...))
address@hidden example
+
+...so basically, inside the first set of parentheses after the
+function name, you specify what (if any) arguments will be passed to
+the command. The second set of parentheses tells StumpWM how to get
+those arguments if they're not explicitly passed to the command. For
+example,
+
address@hidden
+((:string "What do you want to do: "))
address@hidden example
+
+...will read a string from the input the user provides. The quoted
+text is the prompt the user will see. Of course, if you were to, say,
+call the command test, as defined above, from another piece of code,
+it wouldn't give the prompt as long as you fed it arguments.
address@hidden itemize
+
address@hidden
+Note that all commands defined using the defcommand syntax are
+available both to be called with "C-t ;" and from within other lisp
+programs, as though they had been defun-ned (which, in fact, they
+have).
+
address@hidden
+Any code that depends on external libraries or programs that some
+users might not have installed should be placed in the contrib/
+directory.
+
address@hidden
+Don't be afraid to submit your patches to the StumpWM mailing list!
+It may not immediately make it into the official git repository, but
+individual users might find it useful and apply it to their own setup,
+or might be willing to offer suggestions on how to improve the code.
+
address@hidden
+Remember:  StumpWM is designed to run on both clisp and on SBCL. If
+you must use code specific to one or the other, at the very least warn
+people that it only works with one lisp implementation. Better yet,
+figure out how to do it in the other distribution and write a
+statement like this:
+
address@hidden
+#+clisp
+(your-clisp-code)
+#+sbcl
+(your-sbcl-code)
address@hidden example
+
+...to wrap the code for each lisp. Of course, the best option is to
+find a way to use the same code for clisp and SBCL.
address@hidden enumerate
+
address@hidden Using git with StumpWM, , General Advice, Hacking
address@hidden Hacking:  Using git with StumpWM
+
+For quite a while now, StumpWM has been using the git version control
+system for development. If you're one using one of the official
+releases or still using the now-obsolete CVS version, you can get the
+bleeding-edge source code from the official git repository with
+a single command:
+
address@hidden
+$ git clone git://git.savannah.nongnu.org/stumpwm.git
address@hidden example
+
+After this, you'll have a complete git repository, along with the
+complete revision history since the switch. Feel free to play around;
+git has some important features that actually make this safe!
+
+Before we get to that stuff, though, you're going to want to tell git
+about yourself so that your information is included in your commits
+and patches. The very minimum you're going to want to do is:
+
address@hidden
+$ git config --global user.name "Anne N. O'Nymous"
+$ git config --global user.email "anonymous@@foo.org"
address@hidden example
+
+Be sure to check out the manual for git-config--there are several
+options you might want to set, such as enabling colorized output or
+changing the editor and pager you use when making commits and viewing
+logs.
+
+For the sake of argument, let's say you want to make some major
+changes to both user.lisp and core.lisp, add a file called
+DANGEROUS_EXPERIMENT_DO_NOT_USE_OR_ELSE.lisp, and remove the manual
+because you're too 1337 for such things. However, you don't want to
+break your entire StumpWM setup and start over. Thankfully, you don't
+have to. Before you get started, issue this command from the stumpwm
+directory:
+
address@hidden
+$ git checkout -b experimental
address@hidden example
+
+You should now find yourself in a new branch, called experimental. To
+confirm this, type "git branch" (without the quotes); there should be
+an asterisk next to the branch you're currently viewing. At any time,
+you can type "git checkout master" to return to your master branch,
+and at any time you can have as many branches of the project as you
+like. If you want to create a new branch based not on the master
+branch but on your experimental branch, for example, you'd type:
+
address@hidden
+$ git checkout -b new-experiment experimental
address@hidden example
+
+This will place you in a newly-created branch called new-experiment
+which should be identical to your experimental branch as of the last
+commit (more on that soon). If you're actually typing out the
+directions, switch back to your old experimental branch like so:
+
address@hidden
+$ git checkout experimental
address@hidden example
+
+Anyway, now that you have a new branch, create that new file with the
+long name, which I'll just call danger.lisp for brevity. Make whatever
+changes you want to it, and when you're done, tell git about your new
+file.
+
address@hidden
+$ git add dangerous.lisp
address@hidden example
+
+Now, let's pretend you're done making changes. Tell git you're done
+for now:
+
address@hidden
+$ git commit -a
address@hidden example
+
+This will open up a prompt in your editor of choice for you to
+describe your changes. Try to keep the first line short, and then add
+more explanation underneath (for an example, run the command "git log"
+and take a look at some of the longer commit explanations). Save that
+file and then do this:
+
address@hidden
+$ git checkout master
+$ ls
address@hidden example
+
+...and look for your new file. It's not there! That's because you've
+done all of your work in another branch, which git is currently hiding
+from you so that you can "check out" the branch called "master." All
+is as it should be--your master repository is still safe.
+
address@hidden
+$ git checkout experimental
address@hidden example
+
+Now, delete manual.lisp and stumpwm.texi. That's right. Wipe them off
+the face of the Earth, or at least off the hard drive of your
+computer. When you're done, you don't have to tell git you've deleted
+them; it'll figure it out on its own (though things may not compile
+properly unless you edit Makefile.in and stumpwm.asd. Anyway, go ahead
+and edit core.lisp and user.lisp. Really break 'em. Run free! When
+you're done, do another commit, as above, and give it a stupid title
+like "lolz i b0rked stUmpwm guys wTF!?!?!!111!" Now try to compile.
+Just try. It won't work. If it does, you're some kind of savant or
+something. Keep up the good work. If you've actually managed to break
+StumpWM like you were supposed to, never fear! You have two options at
+this point.
+
+One is to go back to the master branch (with another git checkout) and
+just delete your experimental branch, like so:
+
address@hidden
+$ git branch -D
address@hidden example
+
+The "-D" means to force a delete, even if the changes you've made
+aren't available elsewhere. A "-d" means to delete the branch if and
+only if you've merged the changes in elsewhere.
+
+The other option is to create patches for each of your commits so far,
+delete the branch, and then apply any working/wanted patches in a new
+branch. Create your patches (after committing) like so:
+
address@hidden
+$ git format-patch -o patches origin
address@hidden example
+
+(Before doing that you can review your changes with "git log origin..")
+
+You can also use the format-patch command to create a patch of working
+code to send in to the mailing list.
+
+A developer might ask you to try out something they're working on. To
+fetch their master branch, you'd do this:
+
address@hidden
+$ git remote add -f -m master -t master foo git://bar.org/~foo/stumpwm
address@hidden example
+
+...where "foo" is the shorthand name you'll use to refer to that
+repository in the future. To checkout a local copy of that repository,
+you'd then do this:
+
address@hidden
+$ git checkout --track -b foo-master foo/master
address@hidden example
+
+...and could use "git pull foo" to update later while looking at that
+branch (and note that "git pull" with no arguments, in the master
+branch, will update your StumpWM from the official repository.
+
+Finally, if you want to move your experimental changes into your
+master branch, you'd checkout your master branch and run:
+
address@hidden
+$ git merge experimental
address@hidden example
+
+If there are file conflicts, "git diff" will show you where they are;
+you have to fix them by hand. When you're done, do another
+
address@hidden
+$ git commit -a
address@hidden example
+
+...to finalize the changes to your master branch. You can then delete
+your experimental branch. Alternately, you can wait until your changes
+(assuming you sent them in) make it into the official repository
+before deleting your experimental branch.
+
 @node Command and Function Index, Variable Index, Hooks, Top
 @unnumbered Command and Function Index
 @printindex fn
-- 
1.5.5.1