Permalink
Browse files

Added contributing guidelines

  • Loading branch information...
1 parent 94af0e1 commit 7382fed9e0cbcc4eea3d9de384bf111c4509f9ef @assaf committed Dec 25, 2012
Showing with 76 additions and 2 deletions.
  1. +69 −0 CONTRIBUTING.md
  2. +1 −0 doc/new/zombie.js
  3. +2 −2 scripts/{server → live}
  4. +4 −0 scripts/markdown.coffee
View
@@ -0,0 +1,69 @@
+# How to contribute
+
+Follow these six steps:
+
+* Fork the project
+* Write your tests
+* Make your changes
+* Get the tests to pass
+* Update the documentation, if necessary
+* Push to your fork and send a pull request
+
+Documentation changes and refactoring require no new tests. Anything else, if
+it's not covered by a test case, may fail in the future when the code changes
+and there's no test spot the change. If you care enough to see this feature or
+bug fix in production, you should care enough to help us keep it around by
+writing proper test cases.
+
+Some of the things that will increase the chance of your issue getting resolved,
+or your pull request getting accepted:
+
+* Write tests that fail
+* Explain the design of your solution
+* Make it work for everyone, not just one special use case
+* Optimize for code clarity, not cleverness or poetry
+* Follow coding conventions
+
+If in doubt, bring it up for discussion in the [Google
+Group](https://groups.google.com/forum/?hl=en#!forum/zombie-js).
+
+
+## Coding Convention
+
+Our coding style may not be your preferred style, but it's what we got, and
+consistency counts. A lot. So take a few minutes to familiarize yourself with
+the code base. With 10K+ lines of code, you're bound to find an example to
+guide you in anything you need to write.
+
+Specifically:
+
+* We prefer explicit and verbose over crypted and terse
+* We shy away from clever code
+* We're opinonated and use two spaces
+* We understand that parentheses are optional in CoffeeScript, but required to
+ read and understand the code
+* If it lookos like Perl or SQL, it's wrong
+
+
+## Documentation
+
+The documentation is written in [Github-flavored
+Markdown](https://github.com/vmg/sundown).
+
+The easiest way to review the documentation is by running the included server.
+It lets you refresh the browser to see your recent changes.
+
+```sh
+$ ./scripts/live &
+$ open http://localhost:3000
+```
+
+The documentation are also formatted to PDF and Mobi (Kindle). You can generate
+these files yourself (requires `wkhtmltopdf` and `kindlegen`):
+
+```sh
+$ ./scripts/docs
+$ open html/index.html
+$ open html/zombie.pdf
+$ open html/zombie.html
+```
View
@@ -2,6 +2,7 @@ function pageReady() {
var staticLinks = [
["Github", "https://github.com/assaf/zombie"],
["Google Group", "https://groups.google.com/forum/?hl=en#!forum/zombie-js"],
+ ["Contributing", "https://github.com/assaf/zombie/blob/master/CONTRIBUTING.md"],
["PDF", "zombie.pdf"],
["Kindle", "zombie.mobi"]
];
@@ -1,10 +1,10 @@
#!/usr/bin/env coffee
#
-# Simple Web server to serve HTML documentation.
+# Simple Web server to review HTML documentation.
#
# To use:
#
-# ./scripts/server &
+# ./scripts/live &
# open http://localhost:3000
#
# This server is necessary to test some behavior that only works when viewing
View
@@ -1,3 +1,7 @@
+# Process Markdown files, page layout and generates HTML page.
+#
+# Used by scripts/docs and scripts/live.
+
File = require("fs")
NSH = require("node-syntaxhighlighter")
Robotskirt = require("robotskirt")

0 comments on commit 7382fed

Please sign in to comment.