tools: add script to update c-ares

Add a script to automate updating of the c-ares dependency and
accompanying maintenance guide.

Author: richardlau

doc/guides/maintaining-c-ares.md

@@ -0,0 +1,63 @@
+# Maintaining c-ares
+
+Updates to the c-ares dependency involve the following steps:
+1. Downloading the source archive for the new version.
+1. Unpacking the source in a temporary workspace directory.
+1. Removing the `test` directory (to save disk space).
+1. Copying over the existing `.gitignore`, pre-generated `config` directory and
+   `cares.gyp` files.
+1. Replacing the existing `deps/cares` with the workspace directory.
+1. Modifying the `cares.gyp` file for file additions/deletions.
+1. Rebuilding the main Node.js `LICENSE`.
+
+## Running the update script
+
+The `tools/update-cares.sh` script automates the update of the c-ares source
+files, preserving the existing files added by Node.js.
+
+In the following examples, `x.y.z` should match the c-ares version to update to.
+
+```console
+./tools/update-cares.sh x.y.z
+```
+
+e.g.
+```console
+./tools/update-cares.sh 1.18.1
+```
+
+## Check that Node.js still builds and tests
+
+It may be necessary to update `deps/cares/cares.gyp` if any significant changes
+have occurred upstream.
+
+## Rebuild the main Node.js license
+
+Run the `tools/license-builder.sh` script to rebuild the main Node.js `LICENSE`
+file. This may result in no changes if c-ares' license has not changed.
+
+```console
+./tools/license-builder.sh
+```
+
+If the `LICENSE` is updated for changes other than this c-ares update those
+should be done in a separate pull request first.
+
+## Commit the changes
+
+```console
+git add -A deps/cares
+```
+
+Add the rebuilt `LICENSE` if it has been updated.
+```console
+git add LICENSE
+```
+
+Commit the changes with a message like
+
+```text
+deps: update c-ares to x.y.z
+
+Updated as described in doc/guides/maintaining-c-ares.md.
+```

tools/update-cares.sh

@@ -0,0 +1,56 @@
+#!/bin/sh
+set -e
+# Shell script to update c-ares in the source tree to a specific version
+
+BASE_DIR="$( pwd )"/
+DEPS_DIR="$BASE_DIR"deps/
+ARES_VERSION=$1
+
+if [ "$#" -le 0 ]; then
+  echo "Error: please provide an c-ares version to update to"
+  echo "	e.g. $0 1.18.1"
+  exit 1
+fi
+
+echo "Making temporary workspace"
+
+WORKSPACE=$(mktemp -d 2> /dev/null || mktemp -d -t 'tmp')
+
+cleanup () {
+  EXIT_CODE=$?
+  [ -d "$WORKSPACE" ] && rm -rf "$WORKSPACE"
+  exit $EXIT_CODE
+}
+
+trap cleanup INT TERM EXIT
+
+ARES_REF="cares-$(echo "$ARES_VERSION" | tr . _)"
+ARES_TARBALL="c-ares-$ARES_VERSION.tar.gz"
+
+cd "$WORKSPACE"
+
+echo "Fetching c-ares source archive"
+curl -sL -o "$ARES_TARBALL" "https://github.com/c-ares/c-ares/releases/download/$ARES_REF/$ARES_TARBALL"
+gzip -dc "$ARES_TARBALL" | tar xf -
+rm "$ARES_TARBALL"
+mv "c-ares-$ARES_VERSION" cares
+
+echo "Removing tests"
+rm -rf "$WORKSPACE/cares/test"
+
+echo "Copying existing .gitignore, config and gyp files"
+cp -R "$DEPS_DIR/cares/config" "$WORKSPACE/cares"
+cp "$DEPS_DIR/cares/.gitignore" "$WORKSPACE/cares"
+cp "$DEPS_DIR/cares/cares.gyp" "$WORKSPACE/cares"
+
+echo "Replacing existing c-ares"
+rm -rf "$DEPS_DIR/cares"
+mv "$WORKSPACE/cares" "$DEPS_DIR/"
+
+echo "All done!"
+echo ""
+echo "Please git add c-ares, commit the new version:"
+echo ""
+echo "$ git add -A deps/cares"
+echo "$ git commit -m \"deps: update c-ares to $ARES_VERSION\""
+echo ""