Development Instructions

First cut at a document that talks about how we develop, a brief git
tutorial, etc.

docs/development.pod

@@ -0,0 +1,81 @@
+
+=head1 Developing Qpsmtpd
+
+=head2 Mailing List
+
+All qpsmtpd development happens on the qpsmtpd mailing list.
+
+Subscribe by sending mail to qpsmtpd-subscribe@perl.org
+
+=head2 Git
+
+We use git for version control.
+
+Ask owns the master repository at git://github.com/abh/qpsmtpd.git
+
+We suggest using github to host your repository -- it makes your
+changes easily accessible for pulling into the master.  After you
+create a github account, go to
+http://github.com/abh/qpsmtpd/tree/master and click on the "fork"
+button to get your own repository.
+
+=head3 Making a working Copy
+
+ git clone git@github.com:username/qpsmtpd qpsmtpd
+
+will check out your copy into a directory called qpsmtpd
+
+=head3 Committing a change
+
+Edit the appropriate files, and be sure to run the test suite.
+
+  emacs lib/Qpsmtpd.pm # for example
+  perl Makefile.PL
+  make test
+
+When you're ready to check it in...
+
+  git add lib/Qpsmtpd.pm # to let git know you changed the file
+  git commit
+  git push origin # to send to github
+
+=head3 Merging changes back in from the master repository
+
+Tell git about the master repository.  We're going to call it 'abh'
+for now, but you could call it anything you want.  You only have to do
+this once.
+
+  git remote add abh git://github.com/abh/qpsmtpd.git
+
+Pull in data from all remote branches
+
+  git remote update
+
+Forward-port local commits to the updated upstream head
+
+  git rebase abh/master
+
+If you have a change that conflicts with an upstream change (git will
+let you know) you have two options.  You can merge it and then commit
+the merge, or you can skip it entirely:
+
+  git rebase --skip
+
+Be sure to decide whether you're going to skip before you merge, or
+you might get yourself into an odd situation.
+
+Conflicts happen because upstream committers may make minor tweaks to
+your change before applying it.
+
+=head3 Throwing away changes
+
+If you get your working copy into a state you don't like, you can
+always revert to the last commit:
+
+ git reset --hard HEAD
+
+=head3 Applying other peoples changes
+
+One easy way to apply other peoples changes is to use C<git am>.  That
+will go ahead and commit the change.  To modify it, you can use C<git
+commit --amend>.