git.pond.sub.org Git - empserver/blob - doc/contributing

   1                      How to contribute to Empire
   2
   3 Introduction
   4 ------------
   5
   6 Basing your contribution on a tarball may work out okay for simple
   7 patches, but for anything serious, you will need the "git" version
   8 control tools.
   9
  10 The primary purpose of this document is to help you setting up a
  11 proper development environment, and guide you towards good practices.
  12 It is not a git tutorial (but read on for some pointers).  It is not
  13 about how to do the actual hacking; see doc/coding for that.
  14
  15
  16 Getting git
  17 -----------
  18
  19 On Fedora-based systems, do "yum install git".  On Debian-based ones
  20 install the "git-core" package.  You can always download from
  21 <http://git-scm.com/>.
  22
  23 If you're new to git, try the gittutorial(7) manual page, and the Git
  24 User's Manual.  Both are also available at <http://git-scm.com/>,
  25 along with other resources, including the the "Pro Git" book.
  26
  27
  28 Getting sources
  29 ---------------
  30
  31 You can get a copy of the Empire source repository with this command:
  32
  33     $ git clone git://git.pond.sub.org/~armbru/empserver
  34
  35 If that doesn't work because you're behind a restrictive firewall, try
  36
  37     $ git clone http://git.pond.sub.org/empserver
  38
  39 Cloning downloads the entire repository, including revision control
  40 history dating back to 2003.  The repository (the part you download,
  41 and which resides in empserver/.git) currently weighs in at about
  42 25MiB.  But once you got it, you can update it to later versions very
  43 efficiently; see "Pulling updates".
  44
  45 If you prefer working with github, we maintain a mirror at
  46 <https://github.com/gefla/empserver>.
  47
  48
  49 Building
  50 --------
  51
  52 Use of a separate build directory is recommended, like this:
  53
  54     $ cd empserver
  55     $ ./bootstrap
  56     $ mkdir bld
  57     $ cd bld
  58     $ ../configure
  59     $ make
  60     $ make check
  61
  62 See README in the top level directory for more detailed information on
  63 building.
  64
  65
  66 Identify yourself
  67 -----------------
  68
  69 We can only take patches that record authorship.  That is important
  70 not just to give credit where due, but also from a legal standpoint
  71 (see below).  Git records authorship automatically, but you must first
  72 tell git who you are.  That information is best recorded in your
  73 ~/.gitconfig file.  Edit that file, creating it if needed, and put
  74 your name and email address in place of these example values:
  75
  76 [user]
  77         name = Joe X. User
  78         email = joe.user@example.com
  79
  80
  81 Work on a "topic branch"
  82 ------------------------
  83
  84 Cloning the repository created a "master" branch for you, tracking the
  85 origin's master branch.  We recommend you use your master branch only
  86 for tracking the origin, and make all your changes on separate topic
  87 branches, because doing both on the same branch creates problems when
  88 you later pull updates from origin.
  89
  90 If you don't know how to create a branch, check out section "Managing
  91 branches" in gittutorial(7).
  92
  93
  94 Committing changes to your local repository
  95 -------------------------------------------
  96
  97 If you don't know how to commit, check out section "Making changes" in
  98 gittutorial(7).
  99
 100 Commit related changes together, unrelated changes separately.
 101
 102 Write meaningful commit messages.  Start with a single summary line,
 103 followed by a blank line and then a more thorough description.
 104
 105 The purpose of the commit message is not to explain how the code
 106 works; that should be done in the source code itself.  It's to explain
 107 *why* you made the change, and what is affected by it.
 108
 109 The summary line should begin with "keyword: ".  The keyword should
 110 identify what area of Empire gets changed.  Could be a command name, a
 111 directory name, or any other succinct term.  You may want to peruse
 112 commit logs for inspiration.
 113
 114 Keep the summary line short, ideally less than 60 characters.
 115 Nevertheless, it should make sense on its own, independently of the
 116 description.  Yes, coming up with a good summary line can be hard.
 117
 118 The description may be as long as you wish.  Limit line length to 70
 119 characters.  Don't use TABs.
 120
 121 If your commit fixes a bug, point to the commit that introduced the
 122 bug, e.g. "broken in commit 3a7d7fa".  If the bug is in a released
 123 version, add the first release containing it, like "broken in commit
 124 14ea670 (v4.3.8)", or "broken in commit 774b590f, v4.3.17".  If the
 125 bug predates version control, point just to the release.  If you can't
 126 find out when it was broken, say so.
 127
 128 You may want to sign off your commit now by adding a line
 129
 130     Signed-off-by: Your Name <your-email-address>"
 131
 132 The easiest way to do so is "git commit" option -s (assuming you
 133 followed the "Identify yourself" instructions above).
 134
 135 Similar Reported-by:, Tested-by:, and Reviewed-by: lines can be added
 136 to give credit for reporting, testing, and reviewing.  Do not add them
 137 without the credited person's permission.
 138
 139 More on these tags can be found at
 140 <http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html>.
 141
 142
 143 Submitting patches
 144 ------------------
 145
 146 The first step is to prepare patches for e-mail.  Remove any stale
 147 patches you may have lying around:
 148
 149     $ rm *.patch
 150
 151 If you want to submit a single commit, prepare it like this:
 152
 153     $ git format-patch -s -1
 154
 155 This produces a file 0001-<subject>.patch, where <subject> is derived
 156 from the first line of the commit message.
 157
 158 If you want to submit a a whole topic branch based on master, do:
 159
 160     $ git format-patch -ns --cover-letter
 161
 162 This produces 0000-cover-letter.patch 0001-<subject1>.patch
 163 0002-<subject2>.patch and so on.  Edit 0000-cover-letter.patch so it
 164 serves as an introduction to your patch series.
 165
 166 Option -s adds your Signed-off-by, if it's not already present.  Your
 167 Signed-off-by line certifies that you wrote the patch or otherwise
 168 have the right to pass it on, as follows:
 169
 170     Developer's Certificate of Origin 1.1
 171
 172     By making a contribution to this project, I certify that:
 173
 174     (a) The contribution was created in whole or in part by me and I
 175         have the right to submit it under the open source license
 176         indicated in the file; or
 177
 178     (b) The contribution is based upon previous work that, to the best
 179         of my knowledge, is covered under an appropriate open source
 180         license and I have the right under that license to submit that
 181         work with modifications, whether created in whole or in part
 182         by me, under the same open source license (unless I am
 183         permitted to submit under a different license), as indicated
 184         in the file; or
 185
 186     (c) The contribution was provided directly to me by some other
 187         person who certified (a), (b) or (c) and I have not modified
 188         it.
 189
 190     (d) I understand and agree that this project and the contribution
 191         are public and that a record of the contribution (including
 192         all personal information I submit with it, including my
 193         sign-off) is maintained indefinitely and may be redistributed
 194         consistent with
 195         this project or the open source license(s) involved.
 196
 197 Each patch needs to be signed off by everyone who contributed to it,
 198 with their real names, not pseudonym, or else we can't accept it as a
 199 contribution to Empire.
 200
 201 The second step is to e-mail the patches.  Common e-mail programs
 202 notoriously mangle patches.  Therefore, use of "git send-email" is
 203 strongly recommended:
 204
 205     $ git send-email --to wolfpack@wolfpackempire.com *.patch
 206
 207 You may use option --cc to copy yourself and/or other persons.
 208
 209 Some configuration may be required to make "git send-email" work with
 210 your e-mail account.  If you use Gmail, check out
 211 <http://morefedora.blogspot.de/2009/02/configuring-git-send-email-to-use-gmail.html>.
 212
 213 Of course, you can also submit pull requests.
 214
 215
 216 Pulling updates
 217 ---------------
 218
 219 First make sure your working tree is clean, i.e. there are no
 220 uncommitted changes.  You can use "git stash" to save and restore
 221 uncommitted changes.
 222
 223 Switch to branch master:
 224
 225     $ git checkout master
 226
 227 If you mistakenly committed to master, move the commits to a topic
 228 branch, then reset your master to match the origin's:
 229
 230     $ git branch work
 231     $ git reset --hard origin/master
 232
 233 Pull update's from origin into your master:
 234
 235     $ git pull
 236
 237
 238 Rebasing topic branches
 239 -----------------------
 240
 241 After pulling updates, you may want to "rebase" topic branches, so
 242 they branch off the latest master.  The Git User's Manual covers this
 243 in section "Keeping a patch series up to date using git rebase".