feat: add opt-in java/proto check overrides to the metadata update script

.github/workflows/create_new_release_on_new_metadata_update.yml

@@ -6,6 +6,19 @@ on:
   schedule:
     - cron: '0 8 * * *'
   workflow_dispatch:
+    inputs:
+      skip_java_check:
+        description: 'Continue even when the upstream release changes .java files (only tick this once those changes have been reviewed as not needing a port)'
+        type: boolean
+        default: false
+      skip_proto_check:
+        description: 'Continue even when the upstream release changes .proto files'
+        type: boolean
+        default: false
+      dry_run:
+        description: 'Report what the run would do and stop before changing anything - nothing is committed, pushed or released'
+        type: boolean
+        default: false
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -20,14 +33,29 @@ jobs:
   create_new_release_on_new_metadata_update:
     runs-on: ubuntu-latest
     steps:
+      # Credentials are persisted on purpose: the update script pushes through this checkout.
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Setup .NET
         uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5
         with:
-          dotnet-version: 9.x
+          dotnet-version: 10.x
+      # DumpLocale.java regenerates csharp/PhoneNumbers/LocaleData.cs from java.util.Locale,
+      # so the jdk is an input to the generated file rather than an incidental tool. Pinned
+      # to temurin 17 to match the header of the committed LocaleData.cs - changing it would
+      # rewrite the locale data from a different CLDR version.
+      - name: Setup Java
+        uses: actions/setup-java@03ad4de0992f5dab5e18fcb136590ce7c4a0ac95 # v5.6.0
+        with:
+          distribution: temurin
+          java-version: '17'
       - name: Get new metadata information and create new GitHub release
         timeout-minutes: 30
+        # The token is read from GITHUB_TOKEN below rather than passed as an
+        # argument, so it never appears on the process command line.
         run: |
-          bash lib/github-actions-metadata-update.sh ${GITHUB_TOKEN}
+          bash lib/github-actions-metadata-update.sh
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SKIP_JAVA_CHECK: ${{ inputs.skip_java_check || false }}
+          SKIP_PROTO_CHECK: ${{ inputs.skip_proto_check || false }}
+          DRY_RUN: ${{ inputs.dry_run || false }}

README.md

@@ -14,7 +14,7 @@ The original Apache License 2.0 was preserved.
 
 See [this](csharp/README.md) for details about the port.
 
-Phone number metadata is updated in the Google repo approximately every two weeks. This library is automatically updated by a [scheduled github action](https://github.com/twcclegg/libphonenumber-csharp/actions/workflows/create_new_release_on_new_metadata_update.yml) to include the latest metadata, usually within a day.
+Phone number metadata is updated in the Google repo approximately every two weeks. This library is automatically updated by a [scheduled github action](https://github.com/twcclegg/libphonenumber-csharp/actions/workflows/create_new_release_on_new_metadata_update.yml) to include the latest metadata, usually within a day. See [Metadata updates](#metadata-updates) for how that works and how to run it manually.
 
 ## Installation
 
@@ -157,6 +157,49 @@ For more information on metadata usage, please refer to the [main repository faq
 dotnet test csharp/PhoneNumbers.sln
 ```
 
+## Metadata updates
+
+The [`create_new_release_on_new_metadata_update`](https://github.com/twcclegg/libphonenumber-csharp/actions/workflows/create_new_release_on_new_metadata_update.yml) workflow runs daily and drives [`lib/github-actions-metadata-update.sh`](lib/github-actions-metadata-update.sh). When the latest `google/libphonenumber` release is newer than the published NuGet package, it copies the upstream `resources/`, regenerates `csharp/PhoneNumbers/LocaleData.cs`, builds and tests, then commits, pushes and creates a matching GitHub release.
+
+Before doing any of that it inspects the upstream diff and stops if it contains `.java` or `.proto` files, because changes to the Java sources may need porting by hand and an unattended metadata bump would silently skip them.
+
+### Skipping the java (or proto) check
+
+If you have reviewed the upstream diff and the Java changes don't need porting (for example test-only or build-file changes), you can run the update anyway:
+
+* **From the Actions UI** — open [create_new_release_on_new_metadata_update](https://github.com/twcclegg/libphonenumber-csharp/actions/workflows/create_new_release_on_new_metadata_update.yml), click **Run workflow**, and tick **skip_java_check** (and/or **skip_proto_check**). Scheduled runs always leave both unticked.
+* **Locally** — pass the flag or set the environment variable:
+
+  ```bash
+  bash lib/github-actions-metadata-update.sh --skip-java-check "$GITHUB_TOKEN"
+  # or
+  SKIP_JAVA_CHECK=true bash lib/github-actions-metadata-update.sh "$GITHUB_TOKEN"
+  ```
+
+  `--skip-proto-check` / `SKIP_PROTO_CHECK` work the same way, and `--help` lists every option.
+
+Skipping a check means the release ships upstream metadata from a version whose Java-side changes were not ported, so read the upstream diff first — the script prints the offending filenames before it stops.
+
+### Dry runs
+
+`--dry-run` (or the **dry_run** workflow input) runs every read-only step — version lookups, repository checks, the upstream diff gates, the upstream clone — reports what a real run would do, and stops before the first change to the working tree. Nothing is copied, generated, committed, pushed or released, no token is required, and the clean-`main` requirement is relaxed to a warning so it works from a feature branch:
+
+```bash
+# what would tonight's scheduled run do?
+bash lib/github-actions-metadata-update.sh --dry-run
+```
+
+`UPSTREAM_TAG` and `DEPLOYED_VERSION` override the two version lookups, which lets you replay any historical release pair — useful for seeing how a given release trips the gates:
+
+```bash
+UPSTREAM_TAG=v9.0.33 DEPLOYED_VERSION=9.0.32 \
+  bash lib/github-actions-metadata-update.sh --dry-run
+```
+
+### Running it against a fork
+
+Nothing about the target repository is hard-coded. The script commits and pushes through whatever checkout it runs in, and takes the repository to release from `GITHUB_REPOSITORY` — set automatically by GitHub Actions, and otherwise derived from the `origin` remote. So a fork releases to itself, and the dry-run summary names the repository it would publish to. `UPSTREAM_REPOSITORY` (default `google/libphonenumber`) and `NUGET_PACKAGE_ID` (default `libphonenumber-csharp`) are overridable the same way.
+
 ## Contributing
 See [CONTRIBUTING.md](CONTRIBUTING.md)