Skip to content
This repository
Browse code

Added contributing guidelines

  • Loading branch information...
commit 7382fed9e0cbcc4eea3d9de384bf111c4509f9ef 1 parent 94af0e1
Assaf Arkin authored
69  CONTRIBUTING.md
Source Rendered
... ...
@@ -0,0 +1,69 @@
  1
+# How to contribute
  2
+
  3
+Follow these six steps:
  4
+
  5
+* Fork the project
  6
+* Write your tests
  7
+* Make your changes
  8
+* Get the tests to pass
  9
+* Update the documentation, if necessary
  10
+* Push to your fork and send a pull request
  11
+
  12
+Documentation changes and refactoring require no new tests.  Anything else, if
  13
+it's not covered by a test case, may fail in the future when the code changes
  14
+and there's no test spot the change.  If you care enough to see this feature or
  15
+bug fix in production, you should care enough to help us keep it around by
  16
+writing proper test cases.
  17
+
  18
+Some of the things that will increase the chance of your issue getting resolved,
  19
+or your pull request getting accepted:
  20
+
  21
+* Write tests that fail
  22
+* Explain the design of your solution
  23
+* Make it work for everyone, not just one special use case
  24
+* Optimize for code clarity, not cleverness or poetry
  25
+* Follow coding conventions
  26
+
  27
+If in doubt, bring it up for discussion in the [Google
  28
+Group](https://groups.google.com/forum/?hl=en#!forum/zombie-js).
  29
+
  30
+
  31
+## Coding Convention
  32
+
  33
+Our coding style may not be your preferred style, but it's what we got, and
  34
+consistency counts.  A lot.  So take a few minutes to familiarize yourself with
  35
+the code base.  With 10K+ lines of code, you're bound to find an example to
  36
+guide you in anything you need to write.
  37
+
  38
+Specifically:
  39
+
  40
+* We prefer explicit and verbose over crypted and terse
  41
+* We shy away from clever code
  42
+* We're opinonated and use two spaces
  43
+* We understand that parentheses are optional in CoffeeScript, but required to
  44
+  read and understand the code
  45
+* If it lookos like Perl or SQL, it's wrong
  46
+
  47
+
  48
+## Documentation
  49
+
  50
+The documentation is written in [Github-flavored
  51
+Markdown](https://github.com/vmg/sundown).
  52
+
  53
+The easiest way to review the documentation is by running the included server.
  54
+It lets you refresh the browser to see your recent changes.
  55
+
  56
+```sh
  57
+$ ./scripts/live &
  58
+$ open http://localhost:3000
  59
+```
  60
+
  61
+The documentation are also formatted to PDF and Mobi (Kindle).  You can generate
  62
+these files yourself (requires `wkhtmltopdf` and `kindlegen`):
  63
+
  64
+```sh
  65
+$ ./scripts/docs
  66
+$ open html/index.html
  67
+$ open html/zombie.pdf
  68
+$ open html/zombie.html
  69
+```
1  doc/new/zombie.js
@@ -2,6 +2,7 @@ function pageReady() {
2 2
   var staticLinks = [
3 3
     ["Github",        "https://github.com/assaf/zombie"],
4 4
     ["Google Group",  "https://groups.google.com/forum/?hl=en#!forum/zombie-js"],
  5
+    ["Contributing",  "https://github.com/assaf/zombie/blob/master/CONTRIBUTING.md"],
5 6
     ["PDF",           "zombie.pdf"],
6 7
     ["Kindle",        "zombie.mobi"]
7 8
   ];
4  scripts/server → scripts/live
... ...
@@ -1,10 +1,10 @@
1 1
 #!/usr/bin/env coffee
2 2
 #
3  
-# Simple Web server to serve HTML documentation.
  3
+# Simple Web server to review HTML documentation.
4 4
 #
5 5
 # To use:
6 6
 #
7  
-#   ./scripts/server &
  7
+#   ./scripts/live &
8 8
 #   open http://localhost:3000
9 9
 #
10 10
 # This server is necessary to test some behavior that only works when viewing
4  scripts/markdown.coffee
... ...
@@ -1,3 +1,7 @@
  1
+# Process Markdown files, page layout and generates HTML page.
  2
+#
  3
+# Used by scripts/docs and scripts/live.
  4
+
1 5
 File        = require("fs")
2 6
 NSH         = require("node-syntaxhighlighter")
3 7
 Robotskirt  = require("robotskirt")

0 notes on commit 7382fed

Please sign in to comment.
Something went wrong with that request. Please try again.