Make MAPS submodule track latest (branch=master) and add update helper

[Copilot]

Configures the MAPS submodule to track the upstream master branch and provides a standalone helper script for users who prefer not to use git submodule commands.

Changes

• .gitmodules: Added branch = master to enable git submodule update --remote MAPS to fetch latest commits from the tracked branch

• scripts/update_maps.py: Helper script that clones MSM_maps into MAPS if missing, or pulls latest changes if present. Provides clear error messages on git failures.

• MAPS_UPDATE.md: Documents both approaches for updating MAPS with usage examples

Usage

Git submodule approach (developers/CI):

git submodule update --init --remote MAPS

Helper script approach (users):

python3 scripts/update_maps.py

Original prompt

Update the repository so the MAPS submodule tracks the latest commit on the upstream branch named 'master' and add an optional helper script to clone/pull the MSM_maps repo at runtime. Create a small documentation file describing how to update the submodule.

Changes to make:

1. Modify .gitmodules to add branch = master under the MAPS submodule entry.
   • This enables git submodule update --remote MAPS to fetch the latest from the tracked branch.
   • The existing .gitmodules file currently is:

[submodule "MAPS"]
	path = MAPS
	url = https://github.com/drflei/MSM_maps.git

• The new .gitmodules should be:

[submodule "MAPS"]
	path = MAPS
	url = https://github.com/drflei/MSM_maps.git
	branch = master

2. Add a helper script at scripts/update_maps.py that will clone the MSM_maps repo into MAPS if missing, or pull the latest changes from origin/master if present. The script should be safe to run by users and fail with an explanatory message on git errors.

Use this content for scripts/update_maps.py:

#!/usr/bin/env python3
"""
scripts/update_maps.py

Helper to clone or update the MAPS subrepository (MSM_maps).
Run from the repository root (or via python -m scripts.update_maps) to ensure the MAPS directory is populated/updated.
"""
import os
import subprocess
import sys

REPO_URL = "https://github.com/drflei/MSM_maps.git"

# MAPS directory relative to repository root: repo_root/MAPS
here = os.path.dirname(os.path.abspath(__file__))
REPO_ROOT = os.path.normpath(os.path.join(here, os.pardir))
MAPS_DIR = os.path.join(REPO_ROOT, "MAPS")


def run(cmd, check=True):
    print('> ' + ' '.join(cmd))
    return subprocess.run(cmd, check=check)


def ensure_maps():
    maps_path = os.path.abspath(MAPS_DIR)
    if not os.path.exists(maps_path):
        print("Cloning MSM_maps into", maps_path)
        run(["git", "clone", REPO_URL, maps_path])
        # ensure the tracked branch exists locally
        try:
            run(["git", "-C", maps_path, "checkout", "master"])
        except subprocess.CalledProcessError:
            # continue if branch not present locally
            pass
    else:
        print("Pulling latest changes into", maps_path)
        # fetch and pull the configured remote/master
        run(["git", "-C", maps_path, "fetch", "--all"])
        run(["git", "-C", maps_path, "pull", "origin", "master"])


if __name__ == "__main__":
    try:
        ensure_maps()
    except subprocess.CalledProcessError as e:
        print("Error updating MAPS:", e, file=sys.stderr)
        sys.exit(2)

3. Add documentation file MAPS_UPDATE.md explaining how to use the new .gitmodules behaviour and the helper script. Use this content:

name=MAPS_UPDATE.md

# MAPS submodule: tracking latest maps

This repository contains a MAPS submodule that points to the MSM_maps repository. The submodule has been configured to track the upstream branch `master` so you can update it to the latest maps with Git or with the provided helper script.

Options to get the latest maps:

- Using Git (recommended for developers / CI):

  From the repository root:

  ```bash
  git submodule sync --recursive
  git submodule update --init --remote MAPS
  # If you want to persist the new submodule commit in the superproject:
  git add MAPS
  git commit -m "Update MAPS submodule to latest"
  ```

- Using the helper script (convenient for users who don't want to run git submodule commands):

  From the repository root:

  ```bash
  python3 scripts/update_maps.py
  ```

Notes:
- The submodule is configured with `branch = master`. If the upstream branch name changes, update `.gitmodules` accordingly.
- The helper script calls `git clone` / `git pull` and therefore requires `git` to be installed and network access.

4. Commit these changes on a new feature branch and open a pull request against the repository's master branch. The PR title should be: "Make MAPS submodule track latest (branch=master) and add update helper" and include a short description summary of these changes and usage instructions.

Please create the branch from master and open the PR. After creating the PR, provide the PR URL and list the files changed in the PR in the response.

This pull request was created as a result of the following prompt from Copilot chat.

Update the repository so the MAPS submodule tracks the latest commit on the upstream branch named 'master' and add an optional helper script to clone/pull the MSM_maps repo at runtime. Create a small documentation file describing how to update the submodule.

Changes to make:

1. Modify .gitmodules to add branch = master under the MAPS submodule entry.
   • This enables git submodule update --remote MAPS to fetch the latest from the tracked branch.
   • The existing .gitmodules file currently is:

[submodule "MAPS"]
	path = MAPS
	url = https://github.com/drflei/MSM_maps.git

• The new .gitmodules should be:

[submodule "MAPS"]
	path = MAPS
	url = https://github.com/drflei/MSM_maps.git
	branch = master

2. Add a helper script at scripts/update_maps.py that will clone the MSM_maps repo into MAPS if missing, or pull the latest changes from origin/master if present. The script should be safe to run by users and fail with an explanatory message on git errors.

Use this content for scripts/update_maps.py:

#!/usr/bin/env python3
"""
scripts/update_maps.py

Helper to clone or update the MAPS subrepository (MSM_maps).
Run from the repository root (or via python -m scripts.update_maps) to ensure the MAPS directory is populated/updated.
"""
import os
import subprocess
import sys

REPO_URL = "https://github.com/drflei/MSM_maps.git"

# MAPS directory relative to repository root: repo_root/MAPS
here = os.path.dirname(os.path.abspath(__file__))
REPO_ROOT = os.path.normpath(os.path.join(here, os.pardir))
MAPS_DIR = os.path.join(REPO_ROOT, "MAPS")


def run(cmd, check=True):
    print('> ' + ' '.join(cmd))
    return subprocess.run(cmd, check=check)


def ensure_maps():
    maps_path = os.path.abspath(MAPS_DIR)
    if not os.path.exists(maps_path):
        print("Cloning MSM_maps into", maps_path)
        run(["git", "clone", REPO_URL, maps_path])
        # ensure the tracked branch exists locally
        try:
            run(["git", "-C", maps_path, "checkout", "master"])
        except subprocess.CalledProcessError:
            # continue if branch not present locally
            pass
    else:
        print("Pulling latest changes into", maps_path)
        # fetch and pull the configured remote/master
        run(["git", "-C", maps_path, "fetch", "--all"])
        run(["git", "-C", maps_path, "pull", "origin", "master"])


if __name__ == "__main__":
    try:
        ensure_maps()
    except subprocess.CalledProcessError as e:
        print("Error updating MAPS:", e, file=sys.stderr)
        sys.exit(2)

3. Add documentation file MAPS_UPDATE.md explaining how to use the new .gitmodules behaviour and the helper script. Use this content:

name=MAPS_UPDATE.md

# MAPS submodule: tracking latest maps

This repository contains a MAPS submodule that points to the MSM_maps repository. The submodule has been configured to track the upstream branch `master` so you can update it to the latest maps with Git or with the provided helper script.

Options to get the latest maps:

- Using Git (recommended for developers / CI):

  From the repository root:

  ```bash
  git submodule sync --recursive
  git submodule update --init --remote MAPS
  # If you want to persist the new submodule commit in the superproject:
  git add MAPS
  git commit -m "Update MAPS submodule to latest"
  ```

- Using the helper script (convenient for users who don't want to run git submodule commands):

  From the repository root:

  ```bash
  python3 scripts/update_maps.py
  ```

Notes:
- The submodule is configured with `branch = master`. If the upstream branch name changes, update `.gitmodules` accordingly.
- The helper script calls `git clone` / `git pull` and therefore requires `git` to be installed and network access.

4. Commit these changes on a new feature branch and open a pull request against the repository's master branch. The PR title should be: "Make MAPS submodule track latest (branch=master) and add update helper" and include a short description summary of these changes and usage instructions.

Please create the branch from master and open the PR. After creating the PR, provide the PR URL and list the files changed in the PR in the response.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.