Skip to content

Latest commit

 

History

History
291 lines (221 loc) · 9.11 KB

CONTRIBUTING.md

File metadata and controls

291 lines (221 loc) · 9.11 KB
Raw

Contributing Guide

Code of Conduct, Style Guide and Architecture Guide

Please read our code of conduct, style guide and architecture guide before contributing.

Issues

  1. Check for existing issues before creating a new one.
  2. When creating an issue, be clear, provide as much detail as possible and provide examples, when possible.

Pull Requests

  1. Install the Deno CLI.
  2. Fork and clone the repository.
  3. Create a new branch for your changes.
  4. Make your changes and ensure deno task ok passes successfully.
  5. Commit your changes with clear messages.
  6. Submit a pull request with the package in question, and a clear title and description, as follows:
    • fix(http): fix race condition in server
    • docs(fmt): update docstrings
    • feat(log): handle nested messages

Tip

If creating a new package, please add the package name to the scopes list in the title workflow. This must be done a pull request that precedes the pull request that implements the new package.

Suggesting a new feature

When new features are accepted, they are initially accepted as 'unstable' features in the Standard Library. These features are later stabilized after receiving sufficient feedback from the community and the core team.

New features in stable packages (version >= 1.0.0)

If you suggest new APIs in stable packages, which have the version above 1.0.0, you need to implment that API in the file paths of the pattern ./unstable_<api_name>, and the API shouldn't exported from the root module (mod.ts). This is to make it clear which API is stable and which is not.

Example:

encoding
├── base32.ts                      <--- stable API
├── base64.ts                      <--- stable API
├── base64url.ts                   <--- stable API
├── hex.ts                         <--- stable API
├── mod.ts                         <--- stable API
├── unstable_base32_stream.ts      <--- unstable API
├── unstable_base32hex.ts          <--- unstable API
└── unstable_base32hex_stream.ts   <--- unstable API

New features in unstable packages (version < 1.0.0)

There's no special rules to new features in unstable packages. Write new APIs and send a pull request.

Deprecations

  1. See the deprecation policy for how deprecations work.

  2. Start creating a pull request by adding a deprecation notice to the given symbol with the following format, including the removal version and links to any relevant replacement symbols or documentation:

    // /sub/foo.ts
/**
 * @deprecated This will be removed in 0.215.0. Use {@linkcode bar} instead.
 */
export function foo() {}

  3. Submit a pull request starting with the following format:

    deprecation(<package>): <symbol>

Implementations

Assertions

Do not use assertions from @std/assert to assert values in implementation code. Instead, check values inline. @std/assert functions should only be used in testing. See #4865 for details.

Tests

Test names

Use a test name that includes the symbol in question and the test criteria, in plain language, as follows:

  • assertEquals() matches when values are equal
  • ensureDirSync() creates dir if it does not exist
  • Server exposes the addresses the server is listening on as addrs property

Documentation

Symbols and modules are documented using the JSDoc syntax. These guidelines follow the recommendations in the blog post, How to document your JavaScript package.

Public symbols

Where applicable, documentation for public symbols should contain, in order:

  1. A short description, then any further details in new paragraph(s).
  2. A @typeParam tag for each type parameter.
  3. A @param tag for each parameter.
  4. A @returns tag for the return value.
  5. At least one example code snippet using the @example tag and a title. For simple examples which don't need a description, "Usage" is an acceptable title. See Example code snippets below for further guidance.

See the source code within @std/bytes for examples.

Once the documentation for a given package is written, add the package's entry point(s) (usually just mod.ts) to the ENTRY_POINTS array in the documentation checker tool.

Once done, run deno task lint:docs which checks that documentation is complete in the given entry points.

Module documentation

Module files, or mod.ts files, should have the following:

  1. A high-level description of the package.
  2. One example code snippet exhibiting a few APIs within the package. Do not include the @example tag. See Example code snippets below for further guidance.
  3. A @module tag to declare as module documentation.

See the source code for @std/bytes/mod.ts as an example.

Example code snippets

Example code snippets must:

  1. Be as simple yet readable as possible. When in doubt, refer to MDN's Guidelines for writing JavaScript code examples.
  2. Be reproducible as a copied and pasted script.
  3. Use an assertion from @std/assert, when possible. Snippets are run using deno eval in the documentation checker tool and are flagged when they throw an error.

Note: To skip running a specific code snippet, add ignore to the starting delimiter. E.g.

/**
 * ```ts ignore
 * (code snippet will not be run)
 * ```
 */

You can also write code snippets that are expected to fail either at compile time or at runtime by adding expect-error. However, if the fenced code is supposed to not pass type checking, you may also want to specify ignore directive, because we run deno test --doc command in CI, which does type checking against fenced code snippets except for those with ignore directive. So concrete examples are:

/**
 * ```ts expect-error ignore
 * // Does not pass type checking
 * const x: string = 1;
 * ```
 *
 * ```ts expect-error
 * import { assert } from "@std/assert/assert";
 *
 * // Fails at runtime
 * assert(false);
 * ```
 */

Notices for unstable APIs

Each unstable API must have the @experimental TSDoc tag after the starting description.

/**
 * <description>
 *
 * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * ...
 */

Error Messages

User-facing error messages should be clear, concise, and consistent. Error messages should be in sentence case but should not end with a period. Error messages should be free of grammatical errors and typos and written in American English.

⚠️ Note that the error message style guide is a work in progress, and not all the error messages have been updated to conform to the current styles. Error message styles that should be followed:

  1. Messages should start with an upper case:
Bad: cannot parse input
Good: Cannot parse input
  1. Messages should not end with a period:
Bad: Cannot parse input.
Good: Cannot parse input
  1. Message should use quotes for values for strings:
Bad: Cannot parse input hello, world
Good: Cannot parse input "hello, world"
Good: Attempting to grow buffer by 10 bytes, which would exceed the maximum size of 100 bytes
  1. Message should state the action that lead to the error:
Bad: Invalid input x
Good: Cannot parse input x
  1. Active voice should be used:
Bad: Input x cannot be parsed
Good: Cannot parse input x
  1. Messages should not use contractions:
Bad: Can't parse input x
Good: Cannot parse input x
  1. Messages should use a colon when providing additional information. Periods should never be used. Other punctuation may be used as needed:
Bad: Cannot parse input x. value is empty
Good: Cannot parse input x: value is empty
  1. Additional information should describe the current state, if possible, it should also describe the desired state in an affirmative voice:
Bad: Cannot compute the square root for x: value must not be negative
Good: Cannot compute the square root for x: current value is ${x}
Better: Cannot compute the square root for x as x must be >= 0: current value is ${x}

Exceptions

The assertion package uses periods to end sentences in error messages. There are a number of downstream packages that expect this behavior and changing it would be a breaking change.