From c4eac093a7daf3f46f79b359e585e5b1337f7c73 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Sat, 25 May 2013 15:28:16 +0200 Subject: [PATCH] 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 --- README | 3 +- doc/README | 3 + doc/coding | 26 ++--- doc/contributing | 243 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 256 insertions(+), 19 deletions(-) create mode 100644 doc/contributing diff --git a/README b/README index c49894916..c5035470b 100644 --- a/README +++ b/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 diff --git a/doc/README b/doc/README index d16e50cf8..55e51c9bc 100644 --- a/doc/README +++ b/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. diff --git a/doc/coding b/doc/coding index f365835ce..c32b39268 100644 --- a/doc/coding +++ b/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 diff --git a/doc/contributing b/doc/contributing new file mode 100644 index 000000000..1cbbeb1fb --- /dev/null +++ b/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 +. + +If you're new to git, try the gittutorial(7) manual page, and the Git +User's Manual. Both are also available at , +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 +. + + +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 " + +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 +. + + +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-.patch, where 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-.patch +0002-.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 +. + +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". -- 2.43.0