Add CONTRIBUTING.md

.github/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Thank you...
+
+Thank you for your interest in contributing to Deno. Here are a few key areas to
+consider when contributing to Deno.
+
+## Submitting a pull request
+
+Before submitting, please make sure the following is done:
+
+1. Ensure `./tools/test.py` passes.
+2. Format your code with `./tools/format.py`.
+3. Make sure `./tools/lint.py` passes.
+
+## Changes to `third_party`
+
+Changes to `third_party` including any changes in the `package.json` will impact
+the [denoland/deno_third_party](https://github.com/denoland/deno_third_party)
+repository as well.
+
+## Adding Ops (aka bindings)
+
+We are very concerned about making mistakes when adding new APIs. When adding an
+Op to Deno, the counterpart interfaces on other platforms should be researched.
+Please list how this functionality is done in Go, Node, Rust, and Python.
+
+As an example, see how `deno.rename()` was proposed and added in
+[PR #671](https://github.com/denoland/deno/pull/671).
+
+## Documenting APIs
+
+It is important to document public APIs and we want to do that inline with the
+code. This helps ensure that code and documentation are tightly coupled
+together.
+
+### Utilize JSDoc
+
+All publicly exposed APIs and types, both via the `deno` module as well as the
+global/`window` namespace should have JSDoc documentation. This documentation is
+parsed and available to the TypeScript compiler, and therefore easy to provide
+further downstream. JSDoc blocks come just prior to the statement they apply to
+and are denoted by a leading `/**` before terminating with a `*/`. For example:
+
+```ts
+/** A simple JSDoc comment */
+export const FOO = "foo";
+```
+
+### JSDoc style guide
+
+- It is important that documentation is easily human readable, but there is also
+ a need to provide additional styling information to ensure generated
+ documentation is more rich text. Therefore JSDoc should generally follow
+ markdown markup to enrich the text.
+- While markdown supports HTML tags, it is forbidden in JSDoc blocks.
+- Code string literals should be braced with the back-tick (\`) instead of
+ quotes. For example:
+ ```ts
+ /** Import something from the `deno` module. */
+ ```
+- Do not document function arguments unless they are non-obvious of their intent
+ (though if they are non-obvious intent, the API should be considered anyways).
+ Therefore `@param` should generally not be used.
+- Vertical spacing should be minimized whenever possible. Therefore single line
+ comments should be written as:
+ ```ts
+ /** This is a good single line JSDoc */
+ ```
+ And not:
+ ```ts
+ /**
+ * This is a bad single line JSDoc
+ */
+ ```
+- Code examples should not utilise the triple-back tick (\`\`\`) notation or
+ tags. They should just be marked by indentation, which requires a break before
+ the block and 6 additional spaces for each line of the example. This is 4 more
+ than the first column of the comment. For example:
+ ```ts
+ /** A straight forward comment and an example:
+ *
+ * import { foo } from "deno";
+ * foo("bar");
+ */
+ ```
+- Code examples should not contain additional comments. It is already inside a
+ comment. If it needs further comments is not a good example.

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,4 +6,6 @@ Thank you for your pull request. Before submitting, please make sure the followi
 2. Format your code with ./tools/format.py
 3. Make sure ./tools/lint.py passes.
 
+And please read: https://github.com/denoland/deno/blob/master/.github/CONTRIBUTING.md
+
 -->