From 88a920ef43bd0e084ff661b4cc3bdbff98da3044 Mon Sep 17 00:00:00 2001 From: Mohit Mori Date: Tue, 13 May 2025 08:08:27 -0500 Subject: [PATCH 1/3] Updated readme with some clear instructions --- doc/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/README.md b/doc/README.md index a026746ff713a0..c27b9f1a09cbd9 100644 --- a/doc/README.md +++ b/doc/README.md @@ -37,6 +37,8 @@ professionalism across all documents. ### Testing documentation * Validate documentation changes using `make test-doc -j` or `vcbuild test-doc`. +* Node.js uses [remark](https://github.com/remarkjs/remark) and [`remark-preset-lint-node`][] to lint markdown documentation. +* You can run the linter locally with `npm run lint-md` to check your documentation changes. *** From 1a90ac231d8c5acc363b75071e9bb14237fc5c79 Mon Sep 17 00:00:00 2001 From: Mohit Mori Date: Tue, 13 May 2025 08:09:29 -0500 Subject: [PATCH 2/3] Update documentation.md by adding detailed stability overview --- doc/api/documentation.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index c6edb13ad613cd..529bf1e53bda75 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -36,9 +36,11 @@ The stability indexes are as follows: > Experimental features are subdivided into stages: > > * 1.0 - Early development. Experimental features at this stage are unfinished -> and subject to substantial change. +> and subject to substantial change. APIs may be incomplete, inconsistent, or have +> significant breaking changes between releases. > * 1.1 - Active development. Experimental features at this stage are nearing -> minimum viability. +> minimum viability. The core functionality is implemented but may still undergo +> refinement. Some breaking changes could still occur. > * 1.2 - Release candidate. Experimental features at this stage are hopefully > ready to become stable. No further breaking changes are anticipated but may > still occur in response to user feedback. We encourage user testing and @@ -72,7 +74,20 @@ a command-line flag. Experimental features may also emit a [warning][]. ## Stability overview +API stability is a measure of how likely it is that a given feature might change in the future. Each API is labeled with a stability index that indicates its current status. You can find stability information: +1. At the top of each API documentation page +2. Within individual method and class descriptions +3. In tables listing API properties and methods + +Pay close attention to "Stability: 0 - Deprecated" and "Stability: 1 - Experimental" labels when building production applications. For production environments: + +* Avoid using deprecated APIs as they will be removed in future versions +* Use experimental APIs with caution and have contingency plans for breaking changes +* Prefer stable APIs (Stability: 2) for critical application components +* Consider providing feedback on experimental APIs to help improve them + +The stability index helps you make informed decisions about which Node.js features to depend on in your projects. ## JSON output @@ -82,7 +97,16 @@ added: v0.6.12 --> Every `.html` document has a corresponding `.json` document. This is for IDEs -and other utilities that consume the documentation. +and other utilities that consume the documentation. The JSON format contains the same +information as the HTML documentation but structured in a machine-readable format that +enables: + +* Automated documentation tooling +* Integration with code editors for inline documentation +* Third-party documentation viewers and search tools +* Custom documentation processing pipelines + +The JSON files are generated automatically during the documentation build process. ## System calls and man pages From 3759953fc74b3b60755c9252e065ff7482841ff5 Mon Sep 17 00:00:00 2001 From: Mohit Mori Date: Tue, 13 May 2025 08:10:41 -0500 Subject: [PATCH 3/3] Update punycode.md Added whatwag URL explaination --- doc/api/punycode.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/api/punycode.md b/doc/api/punycode.md index f2e9bc09fbbb00..d6e34151c561bb 100644 --- a/doc/api/punycode.md +++ b/doc/api/punycode.md @@ -15,7 +15,11 @@ In a future major version of Node.js this module will be removed. Users currently depending on the `punycode` module should switch to using the userland-provided [Punycode.js][] module instead. For punycode-based URL encoding, see [`url.domainToASCII`][] or, more generally, the -[WHATWG URL API][]. +[WHATWG URL API][], which provides modern internationalization features for URLs. + +**Note:** As of Node.js v21.0.0, this module emits a runtime deprecation warning +when required. Applications relying on this module should migrate to alternatives +as soon as possible. The `punycode` module is a bundled version of the [Punycode.js][] module. It can be accessed using: