contribute.xhtml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4 <html
   5   xmlns="http://www.w3.org/1999/xhtml"
   6   xmlns:xi="http://www.w3.org/2001/XInclude"
   7   xml:lang="en">
   8 <head>
   9   <title>Contribute - HTML Purifier</title>
  10   <xi:include href="common-meta.xml" xpointer="xpointer(/*/node())" />
  11   <meta name="description" content="How to help HTML Purifier grow through code and attention." />
  12   <meta name="keywords" content="HTMLPurifier, HTML Purifier, HTML, filter, filtering, standards, compliant, contribute, contribution, open source, community, help, code, needed" />
  13 </head>
  14 <body>
  15
  16 <xi:include href="common-header.xml" xpointer="xpointer(/*/node())" />
  17 <h1 id="title">Contribute</h1>
  18
  19 <div id="content">
  20
  21 <h2>Why contribute?</h2>
  22
  23 <p>
  24   As open-source software, you are not legally obligated to give anything
  25   back to the community.  In such a sense, HTML Purifier is our gift to
  26   you, and you very well can run away and never be heard from again.
  27 </p>
  28
  29 <p>
  30   We hope, however, that this lack of a legal obligation doesn't prevent
  31   you from contributing back to our project.  Many hours were poured into
  32   this project by its developers, and doubtless, this project has saved
  33   many hours on your behalf.  If HTML Purifier saved you 200 hours of work
  34   (the actual figure might be more, might be less), even if you contribute
  35   ten hours back to the project, that still come out ahead 190 hours.
  36 </p>
  37
  38 <p>
  39   Additionally, your use of this library also requires substantial investment
  40   on your part as well.  You were required to learn the APIs, read the
  41   documentation, tweak things so that they worked with your application,
  42   et cetera.  Contributing back means making good use of this investment:
  43   it means not only will your expertise and knowledge be fed back into
  44   HTML Purifier, but you might learn a thing or to from the internals that
  45   you didn't know before.
  46 </p>
  47
  48 <p>
  49   If I've convinced you, read on! It's quite easy to get started...
  50 </p>
  51
  52 <h2>What can you do?</h2>
  53
  54 <p>
  55   New contributors in other projects often get shoehorned into mundane stuff
  56   like updating documentation or writing tutorials.  Unless that's your
  57   calling, we don't want you to do that.  We want you to scratch an itch,
  58   to think up of something that would be helpful to you, and write code for it.
  59 </p>
  60
  61 <p>
  62   What might that itch be? Over the years, we've accumulated many feature
  63   requests in our <a href="dev/TODO">TODO</a> file.  You might have an
  64   idea for a new AutoFormatter, or maybe would like to implement an HTMLModule
  65   for a set of elements that HTML Purifier doesn't support yet.  Maybe you
  66   want a demo page built-in with the library so that you can easily test
  67   things out without using HTML Purifier's demo page.  Code something that
  68   interests you.
  69 </p>
  70
  71 <h2>Coding standards</h2>
  72
  73 <p>
  74   As a general rule of thumb, make sure your code looks like the code around
  75   it.  Probably the biggest thing is to remember four spaces, no tabs (if you
  76   perpetually forget, get your text-editor to make whitespace visible).
  77 </p>
  78
  79 <p>
  80   The code you write must be PHP 5.0.5 compatible, so avoid later features
  81   like magic methods.  The code you write also must have unit tests, which
  82   reside in the <em>tests/</em> directory.  The workflow for your feature
  83   should be along the lines of:
  84 </p>
  85
  86 <ol>
  87   <li>Write unit tests</li>
  88   <li>Hack hack hack</li>
  89   <li>Run <em>php tests/index.php</em></li>
  90   <li>If failures, go back to 1 or 2</li>
  91 </ol>
  92
  93 <p>
  94   HTML Purifier prides itself in having an evergreen test suite, so if your
  95   change breaks other tests, it probably won't be accepted.
  96 </p>
  97
  98 <h2>Getting setup</h2>
  99
 100 <p>
 101   You already know how to <em>use</em> HTML Purifier. But do you know how
 102   to develop it?
 103 </p>
 104
 105 <h3>Git</h3>
 106
 107 <p>
 108   HTML Purifier's repository is hosted via Git. If you've used Git before,
 109   you can skip this section: you already know what the workflow is for
 110   working on Git, so just clone from git://repo.or.cz/htmlpurifier.git and
 111   get going. Otherwise, read-on.
 112 </p>
 113
 114 <p>
 115   In order to hack on HTML Purifier's source tree, you will first need to
 116   make sure Git is installed on your system. Type the following command
 117   in your prompt:
 118 </p>
 119
 120 <pre class="command">git --version</pre>
 121
 122 <p>
 123   And you should get something along the lines of <q>git version 1.5.6</q>.
 124   Otherwise:
 125 </p>
 126
 127 <dl>
 128   <dt>You use Linux:</dt>
 129   <dd>
 130     Grab Git from your friendly neighborhood package manager. Or compile
 131     from source with package provided at <a href="http://git.or.cz/">git.or.cz</a>.
 132     Either should be relatively simple.
 133   </dd>
 134   <dt>You use Windows:</dt>
 135   <dd>
 136     Download and install <a href="http://code.google.com/p/msysgit/">msysgit</a>.
 137     Then, for all of the following commands
 138     we discuss, enter them in the console provided by Git Bash. If you have
 139     Cygwin, you can also use setup.exe to install Git.
 140   </dd>
 141   <dt>You use a Mac:</dt>
 142   <dd>
 143     There are binaries available from <a href="http://metastatic.org/text/Concern/2007/09/15/new-git-package-for-os-x/">various</a>
 144     <a href="http://code.google.com/p/git-osx-installer/">sources</a>; I haven't
 145     tried them so your mileage may vary. Since Mac is a BSD-like system, you
 146     can also <a href="http://www.dekorte.com/blog/blog.cgi?do=item&amp;id=2539">compile
 147     from source.</a>
 148   </dd>
 149 </dl>
 150
 151 <p>
 152   Run the earlier command again to make sure the installation went
 153   smoothly. Now run this command:
 154 </p>
 155
 156 <pre class="command">git clone git://repo.or.cz/htmlpurifier.git</pre>
 157
 158 <p>
 159   This will copy the HTML Purifier codebase into the htmlpurifier folder.
 160 </p>
 161
 162 <p>
 163   You will want to configure the Git installation with your name and
 164   email address. You can do this with these two commands.
 165 </p>
 166
 167 <pre class="command">git config --global user.name "Bob Doe"
 168 git config --global user.email bob@example.com</pre>
 169
 170 <p>
 171   Let us fast forward for a moment and imagine that we already made our changes
 172   and would now like to send the changes to HTML Purifier for review. You
 173   will to execute these commands:
 174 </p>
 175
 176 <pre class="command">git status</pre>
 177
 178 <p>
 179   This command will give you a quick rundown about all the files Git knows
 180   about. If you have any <q>Untracked files</q>, you will need to add
 181   them with:
 182 </p>
 183
 184 <pre class="command">git add <em>$filename</em></pre>
 185
 186 <blockquote class="aside"><p>
 187   (You can also add <q>Changed but not updated</q> files, but because we will
 188   be using the <code>-a</code> option this is strictly unnecessary.)
 189 </p></blockquote>
 190
 191 <p>
 192   Now, you will want to commit your changes.  Users of centralized version
 193   control systems, beware: this does not push it to a remote repository,
 194   or anything like that. It simply records the change in your local repository.
 195   Doing so is as simple as:
 196 </p>
 197
 198 <pre class="command">git commit -as</pre>
 199
 200 <blockquote class="aside"><p>
 201   The <q>a</q> flag tells Git to commit all modified files, even if you didn't
 202   git add them. The <q>s</q> flag tells Git to sign off your commit message
 203   with your name and email.
 204 </p></blockquote>
 205
 206 <p>
 207   You will then have a screen brought up to enter a commit message. If this
 208   screen is vim, type i, your commit message, ESC, and then :wq ENTER (write and
 209   quit).
 210 </p>
 211
 212 <p>
 213   A quick note about commit messages: there is a very specific format for them.
 214   They should look something like this:
 215 </p>
 216
 217 <pre>Concise one-line statement describing change
 218
 219 Full explanation for the change. If you fixed a bug, make
 220 sure you describe what was wrong, how you fixed it, and
 221 what the behavior is now. If it was a feature, describe
 222 why the feature is useful, how you use it, and any tricky
 223 implementation details.
 224
 225 In short, the body of the commit message (which can span multiple
 226 paragraphs) should, along with the code diff, be self
 227 explanatory and not require any email introduction. At the
 228 same time, your commit message will be immortalized and
 229 should be in third-person and formal.
 230
 231 Signed-off-by: Edward Z. Yang &lt;edwardzyang@thewritingpot.com&gt;</pre>
 232
 233 <p>
 234
 235 </p>
 236
 237 </div>
 238 </body>
 239 </html>