doc/contributing: New file

Partly inspired by GNU coreutils HACKING[*].

doc/coding section "git" is now redundant, except for the note on
avoiding whitespace changes.  Move that to section "Code formatting",
and delete section "git".

[*] http://git.savannah.gnu.org/cgit/coreutils.git/plain/HACKING?id=77da73c

Signed-off-by: Markus Armbruster <armbru@pond.sub.org>

README

@@ -21,7 +21,8 @@ To build the server and set up a game, follow the steps below.
     If you downloaded a tarball, unpack it.
 
     If you cloned a git repository, run bootstrap.  This requires
-    recent versions of Autoconf and Automake to be installed.
+    recent versions of Autoconf and Automake to be installed.  See
+    also doc/contributing.
 
 (2) Building a server
 

doc/README

@@ -38,6 +38,9 @@ pthreads
 coding
 	Guidelines for coding style
 
+contributing
+	How to contribute to Empire
+
 unicode
 	Design and implementation of Empire's Unicode support.
 

doc/coding

@@ -44,6 +44,8 @@ These guidelines don't attempt to be exhaustive.  More complete
 guidelines that are mostly compatible with Empire can be found at
 http://www.jetcafe.org/~jim/c-style.html
 
+See also doc/contributing.
+
 
 Source tree organization
 ------------------------
@@ -78,6 +80,12 @@ you set the style for the current buffer.  Set variable
 `c-default-style' to "stroustrup" to switch to this style for all
 buffers.
 
+Avoid gratuitous space change
+
+Don't change whitespace gratuitiously, say just because your editor
+screws up tabs.  Such changes make it much harder to figure out who
+changed what and when.
+
 Tab character use
 
 Whether you use tab characters or not doesn't really matter that much,
@@ -462,24 +470,6 @@ Others return the same error value for failed read and for successful
 read of input that is invalid.  Then you need to check
 player->aborted; if it is set after a read, the read failed.
 
-
-git
----
-
-Commit related changes together, unrelated changes separately.
-
-Write meaningfull commit messages.  Start with a single short line
-(ideally less than 50 characters) summarizing the change, followed by
-a blank line and then a more thorough description.
-
-The purpose of the change log is not to explain how the code works;
-that should be done in the source code itself.  It's to explain *why*
-you made the change, and what is affected by it.
-
-Don't change whitespace gratuitiously, say just because your editor
-screws up tabs.  Such changes make it much harder to figure out who
-changed what and when.
-
 
 Historical guidelines, superseded by the above
 

doc/contributing

@@ -0,0 +1,243 @@
+                     How to contribute to Empire
+
+Introduction
+------------
+
+Basing your contribution on a tarball may work out okay for simple
+patches, but for anything serious, you will need the "git" version
+control tools.
+
+The primary purpose of this document is to help you setting up a
+proper development environment, and guide you towards good practices.
+It is not a git tutorial (but read on for some pointers).  It is not
+about how to do the actual hacking; see doc/coding for that.
+
+
+Getting git
+-----------
+
+On Fedora-based systems, do "yum install git".  On Debian-based ones
+install the "git-core" package.  You can always download from
+<http://git-scm.com/>.
+
+If you're new to git, try the gittutorial(7) manual page, and the Git
+User's Manual.  Both are also available at <http://git-scm.com/>,
+along with other resources, including the the "Pro Git" book.
+
+
+Getting sources
+---------------
+
+You can get a copy of the Empire source repository with this command:
+
+    $ git clone git://git.pond.sub.org/~armbru/empserver
+
+If that doesn't work because you're behind a restrictive firewall, try
+
+    $ git clone http://git.pond.sub.org/empserver
+
+Cloning downloads the entire repository, including revision control
+history dating back to 2003.  The repository (the part you download,
+and which resides in empserver/.git) currently weighs in at about
+25MiB.  But once you got it, you can update it to later versions very
+efficiently; see "Pulling updates".
+
+If you prefer working with github, we maintain a mirror at
+<https://github.com/gefla/empserver>.
+
+
+Building
+--------
+
+Use of a separate build directory is recommended, like this:
+
+    $ cd empserver
+    $ ./bootstrap
+    $ mkdir bld
+    $ cd bld
+    $ ../configure
+    $ make
+    $ make check
+
+See README in the top level directory for more detailed information on
+building.
+
+
+Identify yourself
+-----------------
+
+We can only take patches that record authorship.  That is important
+not just to give credit where due, but also from a legal standpoint
+(see below).  Git records authorship automatically, but you must first
+tell git who you are.  That information is best recorded in your
+~/.gitconfig file.  Edit that file, creating it if needed, and put
+your name and email address in place of these example values:
+
+[user]
+	name = Joe X. User
+	email = joe.user@example.com
+
+
+Work on a "topic branch"
+------------------------
+
+Cloning the repository created a "master" branch for you, tracking the
+origin's master branch.  We recommend you use your master branch only
+for tracking the origin, and make all your changes on separate topic
+branches, because doing both on the same branch creates problems when
+you later pull updates from origin.
+
+If you don't know how to create a branch, check out section "Managing
+branches" in gittutorial(7).
+
+
+Committing changes to your local repository
+-------------------------------------------
+
+If you don't know how to commit, check out section "Making changes" in
+gittutorial(7).
+
+Commit related changes together, unrelated changes separately.
+
+Write meaningful commit messages.  Start with a single summary line,
+followed by a blank line and then a more thorough description.
+
+The purpose of the commit message is not to explain how the code
+works; that should be done in the source code itself.  It's to explain
+*why* you made the change, and what is affected by it.
+
+The summary line should begin with "keyword: ".  The keyword should
+identify what area of Empire gets changed.  Could be a command name, a
+directory name, or any other succinct term.  You may want to peruse
+commit logs for inspiration.
+
+Keep the summary line short, ideally less than 60 characters.
+Nevertheless, it should make sense on its own, independently of the
+description.  Yes, coming up with a good summary line can be hard.
+
+The description may be as long as you wish.  Limit line length to 70
+characters.  Don't use TABs.
+
+If your commit fixes a bug, point to the commit that introduced the
+bug, e.g. "broken in commit 3a7d7fa".  If the bug is in a released
+version, add the first release containing it, like "broken in commit
+14ea670 (v4.3.8)", or "broken in commit 774b590f, v4.3.17".  If the
+bug predates version control, point just to the release.  If you can't
+find out when it was broken, say so.
+
+You may want to sign off your commit now by adding a line
+
+    Signed-off-by: Your Name <your-email-address>"
+
+The easiest way to do so is "git commit" option -s (assuming you
+followed the "Identify yourself" instructions above).
+
+Similar Reported-by:, Tested-by:, and Reviewed-by: lines can be added
+to give credit for reporting, testing, and reviewing.  Do not add them
+without the credited person's permission.
+
+More on these tags can be found at
+<http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html>.
+
+
+Submitting patches
+------------------
+
+The first step is to prepare patches for e-mail.  Remove any stale
+patches you may have lying around:
+
+    $ rm *.patch
+
+If you want to submit a single commit, prepare it like this:
+
+    $ git format-patch -s -1
+
+This produces a file 0001-<subject>.patch, where <subject> is derived
+from the first line of the commit message.
+
+If you want to submit a a whole topic branch based on master, do:
+
+    $ git format-patch -ns --cover-letter
+
+This produces 0000-cover-letter.patch 0001-<subject1>.patch
+0002-<subject2>.patch and so on.  Edit 0000-cover-letter.patch so it
+serves as an introduction to your patch series.
+
+Option -s adds your Signed-off-by, if it's not already present.  Your
+Signed-off-by line certifies that you wrote the patch or otherwise
+have the right to pass it on, as follows:
+
+    Developer's Certificate of Origin 1.1
+
+    By making a contribution to this project, I certify that:
+
+    (a) The contribution was created in whole or in part by me and I
+	have the right to submit it under the open source license
+	indicated in the file; or
+
+    (b) The contribution is based upon previous work that, to the best
+	of my knowledge, is covered under an appropriate open source
+	license and I have the right under that license to submit that
+	work with modifications, whether created in whole or in part
+	by me, under the same open source license (unless I am
+	permitted to submit under a different license), as indicated
+	in the file; or
+
+    (c) The contribution was provided directly to me by some other
+	person who certified (a), (b) or (c) and I have not modified
+	it.
+
+    (d) I understand and agree that this project and the contribution
+	are public and that a record of the contribution (including
+	all personal information I submit with it, including my
+	sign-off) is maintained indefinitely and may be redistributed
+	consistent with
+        this project or the open source license(s) involved.
+
+Each patch needs to be signed off by everyone who contributed to it,
+with their real names, not pseudonym, or else we can't accept it as a
+contribution to Empire.
+
+The second step is to e-mail the patches.  Common e-mail programs
+notoriously mangle patches.  Therefore, use of "git send-email" is
+strongly recommended:
+
+    $ git send-email --to wolfpack@wolfpackempire.com *.patch
+
+You may use option --cc to copy yourself and/or other persons.
+
+Some configuration may be required to make "git send-email" work with
+your e-mail account.  If you use Gmail, check out
+<http://morefedora.blogspot.de/2009/02/configuring-git-send-email-to-use-gmail.html>.
+
+Of course, you can also submit pull requests.
+
+
+Pulling updates
+---------------
+
+First make sure your working tree is clean, i.e. there are no
+uncommitted changes.  You can use "git stash" to save and restore
+uncommitted changes.
+
+Switch to branch master:
+
+    $ git checkout master
+
+If you mistakenly committed to master, move the commits to a topic
+branch, then reset your master to match the origin's:
+
+    $ git branch work
+    $ git reset --hard origin/master
+
+Pull update's from origin into your master:
+
+    $ git pull
+
+
+Rebasing topic branches
+-----------------------
+
+After pulling updates, you may want to "rebase" topic branches, so
+they branch off the latest master.  The Git User's Manual covers this
+in section "Keeping a patch series up to date using git rebase".