mirror of
https://github.com/denoland/deno.git
synced 2024-12-24 08:09:08 -05:00
96 lines
3.4 KiB
Markdown
96 lines
3.4 KiB
Markdown
# Contributing To Deno
|
|
|
|
Check [the roadmap](https://github.com/denoland/deno/blob/master/Roadmap.md)
|
|
before contributing.
|
|
|
|
Please don't make [the benchmarks](https://denoland.github.io/deno/) worse.
|
|
|
|
Ask for help in the issues or on the
|
|
[chat room](https://gitter.im/denolife/Lobby).
|
|
|
|
Progress towards future releases is tracked
|
|
[here](https://github.com/denoland/deno/milestones).
|
|
|
|
Docs are [here](https://github.com/denoland/deno/blob/master/Docs.md).
|
|
|
|
## 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.
|