Skip to content

Commit

Permalink
doc: make minor fixes to contributing guides
Browse files Browse the repository at this point in the history
PR-URL: #41966
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Derek Lewis <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Darshan Sen <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
  • Loading branch information
mahmoud-moursy authored and danielleadams committed Apr 21, 2022
1 parent edca1cd commit a364810
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 18 deletions.
10 changes: 6 additions & 4 deletions doc/contributing/maintaining-the-build-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,17 @@ There are three main build files that may be directly run when building Node.js:
create platform-dependent build files. Its output is usually in one of these
formats: Makefile, MSbuild, ninja, or XCode project files (the main
Makefile mentioned below is maintained separately by humans). For a detailed
guide on this script, see [configure](#configure).
guide on this script, see [configure][].
* `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a
subset of the targets available in the [Makefile](#makefile), and a few
subset of the targets available in the [Makefile][], and a few
targets of its own. For a detailed guide on this script, see
[vcbuild.bat](#vcbuildbat).
* `Makefile`: A Makefile that can be run with GNU Make. It provides a set of
targets that build and test the Node.js binary, produce releases and
documentation, and interact with the CI to run benchmarks or tests. For a
detailed guide on this file, see [Makefile](#makefile).
detailed guide on this file, see [Makefile][].

On Windows `vcbuild.bat` runs [configure](#configure) before building the
On Windows `vcbuild.bat` runs [configure][] before building the
Node.js binary, on other systems `configure` must be run manually before running
`make` on the `Makefile`.

Expand Down Expand Up @@ -58,3 +58,5 @@ maintained by humans. This is not usually run on Windows, where
of this option.

[GYP]: https://gyp.gsrc.io/docs/UserDocumentation.md
[Makefile]: #makefile
[configure]: #configure
35 changes: 21 additions & 14 deletions doc/contributing/maintaining-types-for-nodejs.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,19 @@
# Maintaining types for Node.js

While JavaScript is an untyped language, there are a number of complementary
technologies like [TypeScript](https://www.typescriptlang.org/) and
[Flow](https://flow.org/) which allow developers to use types within their
JavaScript projects. While many people don't use types, there are enough
who do that the project has agreed it's important to work towards having
[suitable types for end-users](https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md#suitable-types-for-end-users).
While JavaScript is a weakly-typed language, there are some complementary tools
like [TypeScript][] and [Flow][], which allow developers to annotate the source
code of their JavaScript projects. While many people don't annotate their code,
or make use of annotations at all, there are enough who do that the project has
agreed it's important to work towards having [suitable types for end-users][].

## High level approach

There are a number of ways that types could be maintained for Node.js ranging
from shipping them with the Node.js runtime to having them be externally
maintained.

The different options were discussed as part of the
[next-10](https://github.com/nodejs/next-10/blob/main/meetings/summit-nov-2021.md#suitable-types-for-end-users)
effort and it was agreed that maintaining them externally is the best approach.
The different options were discussed as part of the [next-10][] effort and it
was agreed that maintaining them externally is the best approach.
Some of the advantages to this approach include:

* Node.js maintainers do not need to be familiar with any given type
Expand All @@ -34,22 +32,22 @@ The agreement was that the ideal flow would be as follows:

When you run `make doc` the canonical markdown files used to
document the Node.js APIs in the
[doc/api](https://github.com/nodejs/node/tree/master/doc/api)
[doc/api][]
directory are converted to both an `.html` file and a `.json` file.

As part of the regular build/release process both the `html` and
`json` files are published to [nodejs.org](https://nodejs.org/en/docs/).
`json` files are published to [nodejs.org][].

The generator that does the conversion is in the
[tools/doc](https://github.com/nodejs/node/tree/master/tools/doc)
[tools/doc][]
directory.

## Markdown structure

The constraints required on the markdown files in the
[doc/api](https://github.com/nodejs/node/tree/master/doc/api) directory
[doc/api][] directory
in order to be able to generate the JSON files are defined in the
[documentation-style-guide](https://github.com/nodejs/node/blob/master/doc/README.md#documentation-style-guide).
[documentation-style-guide][].

## Planned changes (as of Jan 1 2022)

Expand All @@ -61,3 +59,12 @@ afterwards.
There is an ongoing effort to add additional markdown constraints and
then update the flow in order to be able to generate a better
JSON output.

[Flow]: https://flow.org/
[TypeScript]: https://www.typescriptlang.org/
[doc/api]: https://github.com/nodejs/node/tree/HEAD/doc/api
[documentation-style-guide]: https://github.com/nodejs/node/blob/HEAD/doc/README.md#documentation-style-guide
[next-10]: https://github.com/nodejs/next-10/blob/HEAD/meetings/summit-nov-2021.md#suitable-types-for-end-users
[nodejs.org]: https://nodejs.org/en/docs/
[suitable types for end-users]: https://github.com/nodejs/node/blob/HEAD/doc/contributing/technical-priorities.md#suitable-types-for-end-users
[tools/doc]: https://github.com/nodejs/node/tree/HEAD/tools/doc

0 comments on commit a364810

Please sign in to comment.