about summary refs log tree commit homepage
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2009-09-19 19:01:03 -0700
committerEric Wong <normalperson@yhbt.net>2009-09-19 19:11:21 -0700
commit2730d875650ee8c3121d457743419dce7ce69aef (patch)
tree774b3cead2ca5664766d130908a6c0f9f080b4e8
parent179dec40d0760c2456d1f3e7b94dda5073d5b0a4 (diff)
downloadunicorn-2730d875650ee8c3121d457743419dce7ce69aef.tar.gz
-rw-r--r--.document1
-rw-r--r--HACKING98
2 files changed, 99 insertions, 0 deletions
diff --git a/.document b/.document
index a73dbea..a7632aa 100644
--- a/.document
+++ b/.document
@@ -1,6 +1,7 @@
 README
 TUNING
 PHILOSOPHY
+HACKING
 DESIGN
 CONTRIBUTORS
 LICENSE
diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..5085545
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,98 @@
+= Unicorn Hacker's Guide
+
+== Polyglot Infrastructure
+
+Like Mongrel, we use Ruby where it makes sense, and Ragel with C where
+it helps performance.  All of the code that actually runs your Rack
+application is written Ruby, Ragel or C.
+
+As far as tests and documentation goes, we're not afraid to embrace Unix
+and use traditional Unix tools where they make sense and get the job
+done.
+
+=== Tests
+
+Tests are good, but slow tests make development slow, so we make tests
+faster (in parallel) with GNU make (instead of Rake) and avoiding
+Rubygems.
+
+Since we don't load RubyGems by default, loading Rack properly requires
+setting up RUBYLIB to point to where Rack is located.  Not loading
+Rubygems drastically lowers the time to run the full test suite.  You
+may setup a "local.mk" file in the top-level working directory to setup
+your RUBYLIB and any other environment variables.  A "local.mk.sample"
+file is provided for reference.
+
+Running the entire test suite with 4 tests in parallel:
+
+  make -j4 test
+
+Running just one unit test:
+
+  make test/unit/test_http_parser.rb
+
+Running just one test case in a unit test:
+
+  make test/unit/test_http_parser.rb--test_parse_simple.n
+
+=== HttpServer
+
+We strive to write as little code as possible while still maintaining
+readability.  However, readability and flexibility may be sacrificed for
+performance in hot code paths.  For Ruby, less code generally means
+faster code.
+
+Memory allocation should be minimized as much as practically possible.
+Buffers for IO#readpartial are preallocated in the hot paths to avoid
+building up garbage.  Hash assignments use frozen strings to avoid the
+duplication behind-the-scenes.
+
+We spend as little time as possible inside signal handlers and instead
+defer handling them for predictability and robustness.  Most of the
+Unix-specific things are in the Unicorn::HttpServer class.  Unix systems
+programming experience will come in handy (or be learned) here.
+
+=== Documentation
+
+We use RDoc 2.4.x with Darkfish for documentation as much as possible,
+if you're on Ruby 1.8 you want to install the latest "rdoc" gem.  Due to
+the lack of RDoc-to-manpage converters we know about, we're writing
+manpages in Markdown and converting to troff/HTML with Pandoc.
+
+=== Ruby/C Compatibility
+
+We target Ruby 1.8.6+, 1.9 and will target Rubinius as it becomes
+production-ready.  We need the Ruby implementation to support fork,
+exec, pipe, UNIX signals, access to integer file descriptors and
+ability to use unlinked files.
+
+All of our C code is OS-independent and should run on compilers
+supported by the versions of Ruby we target.
+
+=== Ragel Compatibility
+
+We target the latest released version of Ragel and will update our code
+to keep up with new releases.  Packaged tarballs and gems include the
+generated source code so they will remain usable if compatibility is
+broken.
+
+== Contributing
+
+Contributions are welcome in the form of patches, pull requests, code
+review, testing, documentation, user support or any other feedback is
+welcome.  The mailing list is the central coordination point for all
+user and developer feedback and bug reports.
+
+=== Submitting Patches
+
+Follow conventions already established in the code and do not exceed 80
+characters per line.
+
+Inline patches (from "git format-patch") to the mailing list are
+preferred because they allow code review and comments in the reply to
+the patch.
+
+We will adhere to mostly the same conventions for patch submissions as
+git itself.  See the Documentation/SubmittingPatches document
+distributed with git on on patch submission guidelines to follow.  Just
+don't email the git mailing list or maintainer with Unicorn patches :)