diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7c7035bf190a..84af71cd2076 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -23,21 +23,12 @@ before contributing. 1. Create a new branch for your changes. 1. Make your changes and ensure `deno task ok` passes successfully. 1. Commit your changes with clear messages. -1. Submit a pull request with a clear title and description of your changes and - reference any relevant issues. - - Examples of good titles: - +1. Submit a pull request with the sub-module 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 - Examples of bad titles: - - - fix #7123 - - update docs - - fix bugs - ## Deprecations 1. See the [deprecation policy](/README.md#deprecation-policy) for how @@ -62,12 +53,42 @@ before contributing. ## Tests -1. Use the following convention for test names: - ``` - - ``` +### 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 + +Documentation must be clear, concise and thorough, and be written in +[JSDoc](https://jsdoc.app/) syntax. In general, the documentation style should +be as close to the [MDN Web Docs](https://developer.mozilla.org/) as possible. + +### Public symbols + +For public symbols, include the following pieces of documentation in the +following order (if applicable): + +1. A description of the symbol, including its purpose, what it performs, and + behaviors of various use cases. +1. If it is a function, method or class, a description of each parameter using + the [`@param`](https://jsdoc.app/tags-param) tag. +1. If it is a function or method, a description of the return value using the + [`@returns`](https://jsdoc.app/tags-returns) tag. +1. At least one minimal example code snippet using the + [`@example`](https://jsdoc.app/tags-example) tag for basic usage. The reader + should be able to copy and execute the code snippet with the expected values. + +See the following examples: + +- `copy()` from `std/fs` + ([source](https://github.com/denoland/deno_std/blob/main/fs/copy.ts) and + [documentation](https://jsr.io/@std/fs/doc/~/copy)) - Examples: - - 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 +- `weekOfYear()` from `std/datetime` + ([source](https://github.com/denoland/deno_std/blob/main/datetime/week_of_year.ts) + and [documentation](https://jsr.io/@std/datetime/doc/~/weekOfYear))