Automated process to sync with upstream repository

Author: dbookstaber

.github/workflows/sync-upstream.yml

@@ -0,0 +1,60 @@
+name: Sync Upstream
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Upstream ref (branch/tag or pull/<num>/head)'
+        required: false
+        default: ''
+      clean:
+        description: 'Remove files deleted upstream'
+        required: false
+        default: 'false'
+  # schedule:
+  #   - cron: '17 5 * * *'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Run upstream sync
+        env:
+          SYNC_REF: ${{ github.event.inputs.ref }}
+        run: |
+          if [ "${{ github.event.inputs.clean }}" = "true" ]; then CLEAN_ARG="--clean"; else CLEAN_ARG=""; fi
+          python scripts/sync_upstream.py $CLEAN_ARG
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: |
+            chore(sync): apply upstream changes with pyballistic transforms
+          title: 'Sync from upstream with transformations'
+          body: |
+            This PR was created automatically by the Sync Upstream workflow.
+
+            - Pulls latest from upstream and applies configured transformations
+            - Preserves files listed in `sync_config.json` under `exclude_paths`
+            - See script at `scripts/sync_upstream.py` for details
+
+            If there are unexpected changes, adjust `sync_config.json` or update the script.
+          branch: ci/sync-upstream
+          delete-branch: true
+          signoff: true
+          add-paths: |
+            **/*

.gitignore

@@ -9,10 +9,12 @@
 .vscode
 .coverage
 htmlcov
-debug
-/site/
+**/debug
+**/site
 .env
 .testall
 compile_flags.txt
 # Mirror of Cython sources for coverage lookup:
 /pyballistic_exts/*
+/.sync_upstream/
+/.sync_diff/

README.md

@@ -140,3 +140,16 @@ The calculation results MUST NOT be considered as completely and reliably reflec
 
 THE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
+
+## Keeping in sync with upstream
+
+This repository tracks the upstream project [`py-ballisticcalc`](https://github.com/o-murphy/py-ballisticcalc) while preserving a few local differences (package name, URLs, and select docs like this README).
+
+- Sync locally:
+  - `python scripts/sync_upstream.py` to sync latest `master` from upstream.
+  - `python scripts/sync_upstream.py --ref pull/219/head` to sync a specific PR.
+  - Add `--clean` to remove files deleted upstream (excluded paths remain).
+- Automation:
+  - GitHub Action `Sync Upstream` runs on-demand, opening a PR with changes.  It can also be scheduled to run regularly (uncomment the `schedule` block).
+- Configuration:
+  - See `sync_config.json` for upstream repo/branch, text/path replacements, and excluded files.  Adjust `exclude_paths` if you want additional files to remain customized here.