This is an automated email from the ASF dual-hosted git repository. erisu pushed a commit to branch site/coding-style-guideline in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
commit 74f6b7217023a9e27b16ee1bbac35c432a9edcf2 Author: Erisu <[email protected]> AuthorDate: Thu Jan 8 23:10:35 2026 +0900 site: add coding style guideline --- www/contribute/coding-style-guideline.md | 174 +++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) diff --git a/www/contribute/coding-style-guideline.md b/www/contribute/coding-style-guideline.md new file mode 100644 index 0000000000..577b67898e --- /dev/null +++ b/www/contribute/coding-style-guideline.md @@ -0,0 +1,174 @@ +--- +layout: contribute +title: Apache Cordova Contribute Guidelines +--- + +# Apache Cordova Contributor Coding Style Guidelines + +- [Apache Cordova Contributor Coding Style Guidelines](#apache-cordova-contributor-coding-style-guidelines) + - [Baseline Requirements on All Files](#baseline-requirements-on-all-files) + - [Language-specific Coding Styles](#language-specific-coding-styles) + - [Java](#java) + - [JavaScript](#javascript) + - [Cordova's Modifications to StandardJS Style](#cordovas-modifications-to-standardjs-style) + - [Markdown](#markdown) + - [Cordova's Modifications to markdownlint Style](#cordovas-modifications-to-markdownlint-style) + - [Objective-C](#objective-c) + - [Swift](#swift) + +This document outlines the coding style guidelines for contributing to the Apache Cordova project. The goal is to define a shared minimum baseline across repositories while allowing contributors flexibility in how they write code. + +These guidelines are intended to promote consistency, readability, and maintainability for both current and future contributors. There is no single "preferred" style that all contributors must follow. + +Tooling and CI workflows help validate contributions against a minimum baseline and notifies of issues that were missed. Beyond what can be automatically enforced, reviewers may provide feedback focused on clarity, maintainability, or best practices. When it comes to coding style, anything not listed here is likely to be minor or preference-based. + +Overall, we aim to avoid being overly strict or granular, as unnecessary complexity can make contributing more difficult. Contributing should be approachable and enjoyable—feel free to open a pull request. The GitHub Actions workflows are there to help catch issues, not to create barriers. + +## Baseline Requirements on All Files + +- **LF line endings** + + All text files must use LF line endings to ensure consistency across platforms. Windows uses CRLF by default, which can cause unnecessary diffs and tooling issues for macOS and Linux users. + + This requirement is handled by `.gitattributes` and `.editorconfig`, and validated by GHA. + +- **UTF-8 charset** + + All files must use UTF-8 encoding to ensure consistent text handling across editors and operating systems. + + This requirement is handled by `.editorconfig` and validated by GHA. + +- **Spaces for indentation** + + Spaces are used instead of tabs to avoid indentation inconsistencies between editors. + + This requirement is handled by `.editorconfig` and validated by GHA. + +- **Default indentation size** + + A 4-space indentation is used as the default baseline for readability and consistency across most file types. + + Markdown, YAML, and JSON files use 2-space indentation by convention to align with common tooling and reduce formatting issues. + + This requirement is handled by `.editorconfig` and validated by GHA. + +- **Final newline** + + Files must end with a newline to comply with POSIX text file conventions and avoid diffs at end-of-file. + + This requirement is handled by `.editorconfig` and validated by GHA. + +- **Trailing whitespace** + + Trailing whitespace is trimmed to keep diffs clean and avoid unnecessary formatting changes. + + Markdown files are an exception, as trailing whitespace can be meaningful (for example, to create hard line breaks). + + This behavior is configured in `.editorconfig` and validated by GHA. + +## Language-specific Coding Styles + +### Java + +Cordova's style is based on [Google's Java Style Guide](https://google.github.io/styleguide/javaguide.html) with the following explicit deviations: + +- **Compiler Source:** 11 + + The Java version used for **source code**. `11` means the code is compiled with **Java 11 syntax/features**. + +- **Compiler Compliance:** 11 + + Ensures the compiler **enforces Java 11 language rules**. + +- **Codegen Target Platform:** 11 + + The Java version used for the **generated bytecode**. `11` ensures the compiled classes run on **Java 11 JVMs**. + +- **Line Split:** 140 + + Maximum line length before the formatter **wraps code onto a new line**. + +- **Tabulation Size:** 4 + + Each "tab stop" is **4 spaces**. + +- **Continuation Indentation:** 1 + + When a line is wrapped (e.g., method arguments), it is indented by **1 tab stop** (so 1 × 4 = 4 spaces). + +- **Continuation Indentation for Array Initializer:** 1 + + Similar to above, but specifically for **multi-line array initializations**. + +- **Alignment for Assignment:** 8 + + Controls how the formatter **aligns expressions on the right-hand side of assignments**. Usually a multiple of tab stops for consistency. + +### JavaScript + +Apache Cordova uses **ESLint** to enforce consistent JavaScript style across repositories. All repositories containing JavaScript must include the npm package [**`@cordova/eslint-config`**](https://www.npmjs.com/package/@cordova/eslint-config), and developers are expected to lint code locally or rely on the GitHub Actions workflow, which automatically runs ESLint on commits and pull requests. + +Cordova's JavaScript style is based on **StandardJS**, with a small number of intentional modifications to align with Cordova's long-standing conventions and multi-environment needs (Node.js, browser, and testing). All Cordova JavaScript code is linted using **ES2021 as the minimum baseline** and must conform to ES2021 syntax and semantics at a minimum. + +To understand the baseline behavior, we recommend reviewing the official [StandardJS rules](https://standardjs.com/rules). + +Cordova's ESLint configuration source can be reviewed directly if needed: + +- [Base settings](https://github.com/apache/cordova-eslint/blob/master/lib/base.js) +- [Node settings](https://github.com/apache/cordova-eslint/blob/master/lib/node.js) +- [Test settings](https://github.com/apache/cordova-eslint/blob/master/lib/tests.js) +- [Browser settings](https://github.com/apache/cordova-eslint/blob/master/lib/browser.js) + +#### Cordova's Modifications to StandardJS Style + +Cordova follows **StandardJS**, with the following explicit deviations: + +- **Indentation:** 4 spaces +- **Semicolons:** Required at the end of statements; extra semicolons are disallowed +- **Camelcase:** Current not enforced (snake_case is permitted when appropriate, though camelCase is recommended) + +> [!NOTE] +> While the current `camelCase` convention is relaxed, it will be made stricter to enforce `camelCase` for all variable names. The use of `snake_case`, which is currently permitted, will be limited to constants and must follow the `SCREAMING_UPPER_CASE` format. `camelCase` will continue to be acceptable for constants. + +### Markdown + +In addition to the baseline requirements, Markdown has its own set of linting rules. + +Markdown files are checked using `markdownlint-cli2`, which follows the base rules defined by `markdownlint`. + +See the official rules here: [`markdownlint` Rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). + +We apply rule adjustments that may vary by repository. These adjustments can be found in the `.markdownlint-cli2.yaml` file in each repo. + +#### Cordova's Modifications to markdownlint Style + +Cordova follows **markdownlist**, with the following explicit deviations: + +- **`MD013/line-length`:** Not enforced (There is no character limit to the lenght of a line) + +### Objective-C + +Cordova's style is based on [LLVM Clang-Format Style](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) with the following explicit deviations: + +- **Access modifiers offset:** 0 +- **Short blocks on a single line:** only empty blocks allowed +- **Short enums on a single line:** disallowed +- **Short functions on a single line:** only empty functions allowed +- **Short if statements on a single line:** allowed only without `else` +- **Short lambdas on a single line:** only empty lambdas allowed +- **Braces:** Linux style +- **Column limit:** unlimited +- **Indentation:** 4 spaces +- **Objective-C block indentation:** 4 spaces +- **Objective-C nested block parameters:** do not break before +- **Objective-C property spacing:** space after property +- **Objective-C protocol list spacing:** no space before protocol list +- **Include sorting:** disabled + +### Swift + +Cordova's style is based on the defaults provided by [SwiftLint](https://realm.github.io/SwiftLint/rule-directory.html) with the following explicit deviations: + +- **Line Length:** 140 + + Maximum line length before the formatter **wraps code onto a new line**. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
