diff --git a/docs/guides/javascript/react/conventions.md b/docs/guides/javascript/react/conventions.md new file mode 100644 index 000000000..3ae0221de --- /dev/null +++ b/docs/guides/javascript/react/conventions.md @@ -0,0 +1,44 @@ +--- +title: Coding conventions +tags: + - react + - javascript + - typescript + - moodle +description: Naming and testing conventions that apply to Moodle's TypeScript and React code. +--- + +This page describes the file naming and unit testing conventions that apply to all new TypeScript and TSX code in Moodle, including React components. + +## File naming {/* #file-naming */} + +File names must reflect what the file exports: + +- **React components** must use `PascalCase` (also known as `StudlyCaps`), matching the name of the component they export, for example `ExampleComponent.tsx`. +- **Utility and helper files** (any TypeScript file that is not a React component) must use `camelCase`, for example `dateHelper.ts` or `formatCurrency.ts`. + +```text +public/mod/forum/js/esm/src/ +├── ExampleComponent.tsx // React component: PascalCase +├── GradingPanel.tsx // React component: PascalCase +└── dateHelper.ts // Utility file: camelCase +``` + +Test files follow the name of the file they test, with a `.test` suffix, for example `ExampleComponent.test.ts` or `dateHelper.test.ts`. See [Where to put tests](./testing.md#where-to-put-tests) for the full directory convention. + +## Unit testing requirement {/* #unit-testing-requirement */} + +:::danger[Tests are required] + +All new TypeScript and TSX code **must** be accompanied by Jest unit tests, with a minimum of **80% coverage** of the new code (statements, branches, functions, and lines). Pull requests which add TypeScript or TSX code without corresponding tests, or which fall below this coverage threshold, will not be accepted. + +Use `npm test -- --coverage` to check coverage locally before submitting a pull request. See [Collecting coverage](./testing.md#running-tests) in the testing guide. + +::: + +See the [JavaScript unit testing](./testing.md) guide for details on writing and running Jest tests, including where to place test files and how to mock AMD modules and language strings. + +## See also {/* #see-also */} + +- [JavaScript unit testing](./testing.md) +- [Build tools](./buildtools.md) diff --git a/docs/guides/javascript/react/index.md b/docs/guides/javascript/react/index.md index 227effd7f..e2b1b7f2e 100644 --- a/docs/guides/javascript/react/index.md +++ b/docs/guides/javascript/react/index.md @@ -15,11 +15,16 @@ This section provides an end-to-end overview of React development in Moodle, inc The build documentation explains how React source code is compiled, bundled, and prepared for use in Moodle. It also covers the supporting build tools and common setup requirements. +## Coding conventions + +All new TypeScript and TSX code must follow Moodle's file naming conventions, and must be accompanied by Jest unit tests with a minimum of 80% coverage. See the [coding conventions](./conventions.md) page for details. + ## Unit testing Jest is the JavaScript unit testing framework for React and ESM TypeScript components. The testing guide covers running tests, writing mocks for AMD modules and language strings, module path aliases, and CI integration. ## See also +- [Coding conventions](./conventions.md) - [Build tools](./buildtools.md) - [JavaScript unit testing](./testing.md) diff --git a/docs/guides/javascript/react/testing.md b/docs/guides/javascript/react/testing.md index 012f0333b..ce55564c6 100644 --- a/docs/guides/javascript/react/testing.md +++ b/docs/guides/javascript/react/testing.md @@ -19,6 +19,12 @@ JavaScript unit testing with Jest was introduced in Moodle 5.3 ([MDL-87781](http ::: +:::danger[Tests are required] + +All new TypeScript and TSX code **must** be accompanied by Jest unit tests, with a minimum of **80% coverage** of the new code. See [Coding conventions](./conventions.md#unit-testing-requirement) for the full policy, and [file naming conventions](./conventions.md#file-naming) for how to name your components and test files. + +::: + ## Running tests ```bash @@ -184,6 +190,7 @@ A `Jest` job runs in the GitHub Action pipeline (`.github/workflows/push.yml`) i ## See also +- [Coding conventions](./conventions.md) - [Build tools](./buildtools.md) - [Modules](../modules.md) - [Writing PHPUnit tests](../../testing/index.md) diff --git a/general/development/policies.md b/general/development/policies.md index aac97e36e..1979a40b8 100644 --- a/general/development/policies.md +++ b/general/development/policies.md @@ -78,6 +78,8 @@ In general code should be written to avoid displaying interfaces which are remov All JavaScript must be accessible. +All new TypeScript and TSX code, including React components, must follow Moodle's [file naming conventions](/docs/guides/javascript/react/conventions#file-naming) and must be accompanied by Jest unit tests with a minimum of 80% coverage. See the [React coding conventions](/docs/guides/javascript/react/conventions) for details. + :::info For more about this, see the [JavaScript guide](/docs/guides/javascript). diff --git a/general/development/policies/codingstyle/index.md b/general/development/policies/codingstyle/index.md index 855b1587e..7472f773b 100644 --- a/general/development/policies/codingstyle/index.md +++ b/general/development/policies/codingstyle/index.md @@ -1986,6 +1986,16 @@ PHP includes multiple questionable features that are highly discouraged because 1. do not use `goto`, neither the operator neither labels - use other programming techniques to control the execution flow. 1. do not use `unserialize`, can lead to unintended PHP execution if not used properly with user supplied data - there are better methods of data exchange. +## JavaScript and TypeScript {/* #js-and-ts */} + +This document focuses on PHP. For JavaScript and TypeScript style, see the [JavaScript guide](/docs/guides/javascript) and the [React guide](/docs/guides/javascript/react). + +:::danger[Unit tests are required] + +All new TypeScript and TSX code **must** be accompanied by Jest unit tests, with a minimum of **80% coverage** of the new code. See [Coding conventions](/docs/guides/javascript/react/conventions#unit-testing-requirement) for the full policy. + +::: + ## Policy about coding-style only fixes Way before this coding-style guide was defined and agreed, a lot of code had been written already. Obviously such code does not follow the coding-style at all. While **we enforce conformance for all the new code**, we are not paranoid about the status of all the previous one. @@ -2038,6 +2048,7 @@ This document was drawn from the following sources: ## See also - [JavaScript Coding Style](https://docs.moodle.org/dev/Javascript/Coding_Style) +- [React coding conventions](/docs/guides/javascript/react/conventions) - [CSS Coding Style](https://docs.moodle.org/dev/CSS_Coding_Style) - [SQL coding style](./sql.md) - [Coding](../../policies.md)