From 36ccb6290745078a1cd48de1ec2512f60f7022e4 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 10 Jan 2022 16:13:04 -0500 Subject: [PATCH] doc: document flow for supporting type generation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs: https://github.com/nodejs/next-10/issues/104 Add initial doc to capture how the project supports the flow for types generation. Based on discussions from the Next-10 mini-summit that included project members and members of the Definitely Typed team. Will need to be updated as we improve the flow and resulting json but captures the current flow and approach and will give us the place where we can update as things change. Signed-off-by: Michael Dawson PR-URL: https://github.com/nodejs/node/pull/41464 Reviewed-By: James M Snell Reviewed-By: Chengzhong Wu Reviewed-By: Michaël Zasso --- .../maintaining-types-for-nodejs.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 doc/contributing/maintaining-types-for-nodejs.md diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md new file mode 100644 index 00000000000000..5cc52bd6ce931e --- /dev/null +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -0,0 +1,63 @@ +# 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). + +## 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. +Some of the advantages to this approach include: + +* Node.js maintainers do not need to be familiar with any given type + system/technology. +* Types can be updated without requiring Node.js releases. + +The agreement was that the ideal flow would be as follows: + +* APIs are added/documented in the existing Node.js markdown files. +* Automation in the Node.js project creates a machine readable JSON + representation of the API from the documentation. +* Automation within external type projects consumes the JSON and automatically + generates a PR to add the API. + +## Generation/Consumption of machine readable JSON files + +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) +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/). + +The generator that does the conversion is in the +[tools/doc](https://github.com/nodejs/node/tree/master/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 +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). + +## Planned changes (as of Jan 1 2022) + +While JSON files are already being generated and published, they are not +structured well enough for them to be easily consumed by the type projects. +Generally external teams need some custom scripts along with manual fixup +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.