doc,deps: document how to maintain ICU in Node.js

- update v8 guide to mention ICU
- move content from the tools/icu/README.md but leave a pointer

Fixes: https://github.com/nodejs/node/issues/26108
Co-Authored-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/30607

Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>

1 files changed, 18 insertions, 115 deletions

diff --git a/tools/icu/README.md b/tools/icu/README.md
index 89a70e7087..1af39941b5 100644
--- a/tools/icu/README.md
+++ b/tools/icu/README.md
@@ -1,8 +1,9 @@
 # Notes about the `tools/icu` subdirectory
 
-This directory contains tools, data, and information about the [ICU](http://icu-project.org)
-(International Components for Unicode) integration. ICU is used to provide
-internationalization functionality.
+This directory contains tools, data, and information about the
+International Components for Unicode integration. [ICU][] is used
+both by V8 and also by
+Node.js itself to provide internationalization functionality.
 
 * `patches/` are one-off patches, actually entire source file replacements,
   organized by ICU version number.
@@ -18,119 +19,21 @@ internationalization functionality.
 * `README.md` — you are here
 * `shrink-icu-src.py` — this is used during upgrade (see guide below)
 
-## How to upgrade ICU
+Note:
+> The files in this directory were written for the Node.js v0.12 effort.
+> The original intent was to merge the tools such as `icutrim.py` and `iculslocs.cc`
+> back into ICU. ICU has gained its own “data slicer” tool.
+> There is an issue open, https://github.com/nodejs/node/issues/25136
+> for replacing `icutrim.py` with the [ICU data slicer][].
 
-* Make sure your Node.js workspace is clean (clean `git status`) should be
-  sufficient.
-* Configure Node.js with the specific [ICU version](http://icu-project.org/download)
-  you want to upgrade to, for example:
+## See Also
 
-```shell
-./configure \
-    --with-intl=full-icu \
-    --with-icu-source=http://download.icu-project.org/files/icu4c/58.1/icu4c-58_1-src.tgz
-make
-```
+* [docs/guides/maintaining-icu.md](../../doc/guides/maintaining-icu.md) for
+information on maintaining ICU in Node.js
 
-> _Note_ in theory, the equivalent `vcbuild.bat` commands should work also,
-> but the commands below are makefile-centric.
+* [docs/api/intl.md](../../doc/api/intl.md) for information on the
+internationalization-related APIs in Node.js
+* [The ICU Homepage][ICU]
 
-* If there are ICU version-specific changes needed, you may need to make changes
-  in `icu-generic.gyp` or add patch files to `tools/icu/patches`.
-  * Specifically, look for the lists in `sources!` in the `icu-generic.gyp` for
-  files to exclude.
-
-* Verify the Node.js build works:
-
-```shell
-make test-ci
-```
-
-Also running
-
-<!-- eslint-disable strict -->
-
-```js
-new Intl.DateTimeFormat('es', {month: 'long'}).format(new Date(9E8));
-```
-
-…Should return `enero` not `January`.
-
-* Now, copy `deps/icu` over to `deps/icu-small`
-
-```shell
-python tools/icu/shrink-icu-src.py
-```
-
-* Now, do a clean rebuild of Node.js to test:
-
-```shell
-make -k distclean
-./configure
-make
-```
-
-* Test this newly default-generated Node.js
-
-<!-- eslint-disable strict -->
-
-```js
-process.versions.icu;
-new Intl.DateTimeFormat('es', {month: 'long'}).format(new Date(9E8));
-```
-
-(This should print your updated ICU version number, and also `January` again.)
-
-You are ready to check in the updated `deps/small-icu`. This is a big commit,
-so make this a separate commit from the smaller changes.
-
-* Now, rebuild the Node.js license.
-
-```shell
-# clean up - remove deps/icu
-make clean
-tools/license-builder.sh
-```
-
-* Update the URL and hash for the full ICU file in `tools/icu/current_ver.dep`.
-It should match the ICU URL used in the first step.  When this is done, the
-following should build with small ICU.
-
-```shell
-# clean up
-rm -rf out deps/icu deps/icu4c*
-./configure --with-intl=small-icu --download=all
-make
-make test-ci
-```
-
-* commit the change to `tools/icu/current_ver.dep` and `LICENSE` files.
-
-  * Note: To simplify review, I often will “pre-land” this patch, meaning that
-  I run the patch through `curl -L https://github.com/nodejs/node/pull/xxx.patch
-  | git am -3 --whitespace=fix` per the collaborator’s guide… and then push that
-  patched branch into my PR's branch. This reduces the whitespace changes that
-  show up in the PR, since the final land will eliminate those anyway.
-
------
-
-## Postscript about the tools
-
-The files in this directory were written for the Node.js effort.
-It was the intent of their author (Steven R. Loomis / srl295) to
-merge them upstream into ICU, pending much discussion within the
-ICU-TC.
-
-`icu_small.json` is somewhat node-specific as it specifies a "small ICU"
-configuration file for the `icutrim.py` script. `icutrim.py` and
-`iculslocs.cpp` may themselves be superseded by components built into
-ICU in the future. As of this writing, however, the tools are separate
-entities within Node.js, although theyare being scrutinized by interested
-members of the ICU-TC. The “upstream” ICU bugs are given below.
-
-* [#10919](http://bugs.icu-project.org/trac/ticket/10919)
-  (experimental branch - may copy any source patches here)
-* [#10922](http://bugs.icu-project.org/trac/ticket/10922)
-  (data packaging improvements)
-* [#10923](http://bugs.icu-project.org/trac/ticket/10923)
-  (rewrite data building in python)
+[ICU data slicer]: https://github.com/unicode-org/icu/blob/master/docs/userguide/icu_data/buildtool.md
+[ICU]: http://icu-project.org