Update CHANGELOG and README

Author: aomarks

CHANGELOG.md

@@ -6,7 +6,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic
 Versioning](https://semver.org/spec/v2.0.0.html).
 
-<!-- ## Unreleased -->
+## Unreleased
+
+### Changed
+
+- It is now supported _and preferred_ to use `#` as the delimiter between
+  packages and scripts in dependency specifiers, instead of `:`. For example,
+  instead of `"../other:build"`, it is now preferred to write
+  `"../other#build"`.
+
+  The `:` character will continue to work the same indefinitely, but the Wireit
+  documentation will exclusively show `#`, and upcoming new features for
+  dependency specifiers will only work with the newer `#` form.
+
+- **[BREAKING]** Certain special characters must now be escaped with a `\`
+  (which in JSON is written as `\\`) if they are to be intepreted literally in a
+  package specifier:
+
+  - `#`
+  - `\`
+  - `<`
+  - `>`
+  - `.` (only required at the start of the specifier)
+  - `!` (only required at the start of the specifier)
+  - `:` (only required when using the legacy delimiter, meaning a `#` does not
+    appear later in the specifier)
+
+  For example, in the (highly unusual) situation that you depend on a script
+  like `"../ha#shy:sl\\ashy"`, you should now write `"../ha\\#shy#sl\\\\ashy"`
+  (note that `\` escapes are _also_ required for JSON, hence the double
+  escapes).
 
 ## [0.14.11] - 2025-02-07
 

README.md

@@ -171,10 +171,14 @@ other wireit scripts, and can never be run directly.
 ### Cross-package dependencies
 
 Dependencies can refer to scripts in other npm packages by using a relative path
-with the syntax `<relative-path>:<script-name>`. All cross-package dependencies
+with the syntax `<relative-path>#<script-name>`. All cross-package dependencies
 should start with a `"."`. Cross-package dependencies work well for npm
 workspaces, as well as in other kinds of monorepos.
 
+> [!NOTE] The `:` character also be used as a delimiter instead of `#` (e.g.
+> `"../other-package:build`), but `#` is preferred since February 2025 because
+> it is less ambiguous given the prevalence of `:` in npm script names.
+
 ```json
 {
   "scripts": {
@@ -183,7 +187,7 @@ workspaces, as well as in other kinds of monorepos.
   "wireit": {
     "build": {
       "command": "tsc",
-      "dependencies": ["../other-package:build"]
+      "dependencies": ["../other-package#build"]
     }
   }
 }
@@ -534,7 +538,7 @@ expected to exit by itself, set `"service": true`.
       "dependencies": [
         "build:server",
         {
-          "script": "../assets:build",
+          "script": "../assets#build",
           "cascade": false
         }
       ]
@@ -691,7 +695,7 @@ There are two main reasons you might want to set `cascade` to `false`:
          "dependencies": [
            "build:server",
            {
-             "script": "../assets:build",
+             "script": "../assets#build",
              "cascade": false
            }
          ],
@@ -853,7 +857,7 @@ The following properties can be set inside `wireit.<script>` objects in
 | ------------------------- | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | `command`                 | `string`                           | `undefined`             | The shell command to run.                                                                                                       |
 | `dependencies`            | `string[] \| object[]`             | `[]`                    | [Scripts that must run before this one](#dependencies).                                                                         |
-| `dependencies[i].script`  | `string`                           | `undefined`             | [The name of the script, when the dependency is an object.](#dependencies).                                                     |
+| `dependencies[i].script`  | `string`                           | `undefined`             | [The name of the script, when the dependency is an object](#dependencies).                                                      |
 | `dependencies[i].cascade` | `boolean`                          | `true`                  | [Whether this dependency always causes this script to re-execute](#execution-cascade).                                          |
 | `files`                   | `string[]`                         | `undefined`             | Input file [glob patterns](#glob-patterns), used to determine the [fingerprint](#fingerprint).                                  |
 | `output`                  | `string[]`                         | `undefined`             | Output file [glob patterns](#glob-patterns), used for [caching](#caching) and [cleaning](#cleaning-output).                     |