plone · petschki · Sep 23, 2026 · Sep 17, 2026 · Sep 17, 2026 · Sep 22, 2026
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -3,13 +3,15 @@ graft docs
 include *.rst
 global-exclude *.pyc
 include pyproject.toml
+include resource-versions.json
 recursive-exclude news *
 exclude news
 exclude .coveragerc
 # exclude npmjs resources
 exclude package.json
 exclude .prettierrc.json
 exclude Makefile
+prune scripts
 exclude babel.config.js
 exclude webpack.config.js
 exclude pnpm-lock.yaml

diff --git a/Makefile b/Makefile
@@ -1,206 +1,109 @@
 BUNDLE_DIR = src/plone/staticresources/static/bundle-plone
 BOOTSTRAP_ICONS_DIR = src/plone/staticresources/static/icons-bootstrap
-BOOTSTRAP_ICONS_BASENAME = bootstrap-icons-$(patsubst v%,%,$(BOOTSTRAP_ICONS_VERSION))
 COUNTRY_FLAGS_DIR = src/plone/staticresources/static/icons-country-flags
 
-# Run each recipe in one shell so an early exit skips its remaining commands.
-# Keep stopping immediately when a command fails.
-.ONESHELL:
-.SHELLFLAGS = -ec
-
-
-# Prerequisites:
+# Prerequisites (checked by `make check-dependencies`):
 # - make
 # - curl
 # - git
 # - jq
+# - tar
+# - python3 (including the venv and ensurepip modules)
+REQUIRED_COMMANDS = curl git jq tar python3
 
 
 .PHONY: all
 all: update-mockup update-bootstrap-icons update-country-flags
 
 
+# Show the versions of the installed resources.
+.PHONY: versions
+versions:
+	@jq . resource-versions.json
+
+
 .PHONY: clean
 clean:
 	rm -Rf .venv
 
 
-./.venv/bin/python install:
-	`which python3` -m venv .venv
-	./.venv/bin/pip install lxml
+# Check that all commands required by the update scripts are available and
+# print installation hints for the missing ones.
+.PHONY: check-dependencies
+check-dependencies:
+	@missing=""; \
+	for cmd in $(REQUIRED_COMMANDS); do \
+		command -v "$$cmd" > /dev/null 2>&1 || missing="$$missing $$cmd"; \
+	done; \
+	if [ -n "$$missing" ]; then \
+		echo "❌ Missing required commands:$$missing" >&2; \
+		echo "   Install them with your package manager, e.g.:" >&2; \
+		echo "   macOS (Homebrew): brew install$$missing" >&2; \
+		echo "   Debian/Ubuntu:    sudo apt install$$missing" >&2; \
+		echo "   Fedora:           sudo dnf install$$missing" >&2; \
+		exit 1; \
+	fi; \
+	if ! python3 -c "import venv, ensurepip" > /dev/null 2>&1; then \
+		echo "❌ python3 cannot create virtual environments (venv/ensurepip missing)." >&2; \
+		echo "   Debian/Ubuntu: sudo apt install python3-venv" >&2; \
+		exit 1; \
+	fi
+
+
+# Create the virtual environment only if it is missing or broken, e.g. when it
+# was created by a Python interpreter which no longer exists. `--clear` avoids
+# mixing different Python versions in the same virtual environment.
+.PHONY: install
+install: check-dependencies
+	@if ! ./.venv/bin/python -c "import lxml" > /dev/null 2>&1 \
+		|| ! ./.venv/bin/towncrier --version > /dev/null 2>&1; then \
+		echo "🐍 Create virtual environment in .venv with `command -v python3`."; \
+		python3 -m venv --clear .venv \
+		&& ./.venv/bin/pip install --quiet lxml towncrier; \
+	fi
 
 
-# Download a Mockup universal bundle from GitHub releases and replace
-# the existing one.
+# Download the Mockup universal bundle with the npm dist-tag `latest` from the
+# npm registry and replace the existing one.
 #
 # You can use the `MOCKUP_VERSION` environment variable to download a
 # specific version, e.g. a pre-release version which would not be picked up
 # automatically:
 # `MOCKUP_VERSION=5.7.0-alpha.2 make update-mockup`
 #
 .PHONY: update-mockup
-update-mockup:
-ifndef MOCKUP_VERSION
-	@echo "🧪 Get the latest Mockup version from GitHub (no pre-release)."
-
-	@# If no MOCKUP_VERSION environment variable is defined,
-	@# Get the latest version from the GitHub API.
-	# Also see: https://stackoverflow.com/a/42040905/1337474
-	$(eval MOCKUP_VERSION := $(shell curl https://api.github.com/repos/plone/mockup/releases/latest -s | jq .tag_name -r))
-	@echo "🏷️  Mockup version is: $(MOCKUP_VERSION)"
-
-endif
-	@echo "🧪 Copy bundle from GitHub."
-
-	@# Download the Mockup bundle.
-	wget https://github.com/plone/mockup/releases/download/$(MOCKUP_VERSION)/mockup-bundle-$(MOCKUP_VERSION).zip 1> /dev/null 2> /dev/null
-	@unzip mockup-bundle-$(MOCKUP_VERSION).zip > /dev/null
-	@# Replace the old Mockup bundle with the new one.
-	@rm -Rf $(BUNDLE_DIR)
-	@mv mockup-bundle-$(MOCKUP_VERSION) $(BUNDLE_DIR)
-	@# Cleanup.
-	@rm mockup-bundle-$(MOCKUP_VERSION).zip
-
-	@echo "🧪 Check for resource changes."
-	@git add $(BUNDLE_DIR)
-	@if git diff --cached --quiet -- $(BUNDLE_DIR); then
-		echo "ℹ️ Mockup is unchanged; no changelog entry or commit created."
-		exit 0
-	fi
-
-	@echo "🧪 Git add and commit."
-	@# Add changelog entry
-	@towncrier create +update-mockup.feature \
-		--content "Update Mockup to $(MOCKUP_VERSION)."
-	@# Add with a `*` in case a number was appended due to a naming conflict.
-	@git add news/+update-mockup.feature*
+update-mockup: install
+	@sh scripts/update_mockup.sh "$(BUNDLE_DIR)" "$(MOCKUP_VERSION)" latest
 
-	@# commit
-	@git commit -m"Update Mockup to $(MOCKUP_VERSION)." > /dev/null
 
-	@# Spit out info.
-	@echo ""
-	@echo "📦 Mockup static folder size is: "
-	@cd $(BUNDLE_DIR) && du -sh
-	@echo ""
-	@echo "🚀 Updated Mockup to $(MOCKUP_VERSION)."
-	@echo ""
+# Download the newest Mockup pre-release from the npm registry: the highest
+# version among the dist-tags `alpha`, `beta` and `rc`, which is higher than
+# `latest`. Use `MOCKUP_VERSION` to select a specific version instead.
+.PHONY: update-mockup-prerelease
+update-mockup-prerelease: install
+	@sh scripts/update_mockup.sh "$(BUNDLE_DIR)" "$(MOCKUP_VERSION)" prerelease
 
 
-# Download bootstrap-icons from GitHub releases and replace the existing one.
+# Download bootstrap-icons from the npm registry and replace the existing one.
+# Only the SVG icons are copied.
 #
 # You can use the `BOOTSTRAP_ICONS_VERSION` environment variable to download a
 # specific version, e.g. a pre-release version which would not be picked up
 # automatically:
-# `BOOTSTRAP_ICONS_VERSION=5.7.0-alpha.2 make update-bootstrap-icons`
+# `BOOTSTRAP_ICONS_VERSION=1.13.1 make update-bootstrap-icons`
 #
 .PHONY: update-bootstrap-icons
 update-bootstrap-icons: install
-ifndef BOOTSTRAP_ICONS_VERSION
-	@echo "🧪 Get the latest Bootstrap Icons version from GitHub (no pre-release)."
-
-	@# If no BOOTSTRAP_ICONS_VERSION environment variable is defined,
-	@# Get the latest version from the GitHub API.
-	# Also see: https://stackoverflow.com/a/42040905/1337474
-	$(eval BOOTSTRAP_ICONS_VERSION := $(shell curl https://api.github.com/repos/twbs/icons/releases/latest -s | jq .tag_name -r))
-	@echo "🏷️  Bootstrap Icons version is: $(BOOTSTRAP_ICONS_VERSION)"
-
-endif
-	@echo "🧪 Copy bootstrap-icons from GitHub."
-
-	@# Download the Bootstrap Icons bundle.
-	wget https://github.com/twbs/icons/releases/download/$(BOOTSTRAP_ICONS_VERSION)/$(BOOTSTRAP_ICONS_BASENAME).zip 1> /dev/null 2> /dev/null
-	@unzip $(BOOTSTRAP_ICONS_BASENAME).zip > /dev/null
-	@# Replace the old Bootstrap Icons bundle with the new one.
-	@rm -Rf $(BOOTSTRAP_ICONS_DIR)
-	@mv $(BOOTSTRAP_ICONS_BASENAME) $(BOOTSTRAP_ICONS_DIR)
-	@# Cleanup.
-	@rm $(BOOTSTRAP_ICONS_BASENAME).zip
-
-	@echo "✳️ Register bootstrap icons"
-	./.venv/bin/python src/plone/staticresources/_scripts/register_icons.py
-	./.venv/bin/python src/plone/staticresources/_scripts/iconmap_json.py
-
-	@echo "🧪 Check for resource changes."
-	@git add $(BOOTSTRAP_ICONS_DIR)
-	@git add src/plone/staticresources/profiles/default/registry/icons_bootstrap.xml
-	@git add src/plone/staticresources/static/iconmap.json
-	@if git diff --cached --quiet -- $(BOOTSTRAP_ICONS_DIR) \
-		src/plone/staticresources/profiles/default/registry/icons_bootstrap.xml \
-		src/plone/staticresources/static/iconmap.json; then
-		echo "ℹ️ Bootstrap Icons are unchanged; no changelog entry or commit created."
-		exit 0
-	fi
-
-	@echo "🧪 Git add and commit."
-	@# Add changelog entry
-	@towncrier create +update-bootstrap-icons.feature \
-		--content "Update Bootstrap Icons to $(BOOTSTRAP_ICONS_VERSION)."
-	@# Add with a `*` in case a number was appended due to a naming conflict.
-	@git add news/+update-bootstrap-icons.feature*
+	@sh scripts/update_bootstrap_icons.sh "$(BOOTSTRAP_ICONS_DIR)" "$(BOOTSTRAP_ICONS_VERSION)"
 
-	@# commit
-	@git commit -m"Update Bootstrap Icons to $(BOOTSTRAP_ICONS_VERSION)." > /dev/null
 
-	@# Spit out info.
-	@echo ""
-	@echo "📦 Bootstrap Icons static folder size is: "
-	@cd $(BOOTSTRAP_ICONS_DIR) && du -sh
-	@echo ""
-	@echo "🚀 Updated Bootstrap Icons to $(BOOTSTRAP_ICONS_VERSION)."
-	@echo "‼️ Don't forget to create an upgrade step for the new icons (see upgrade 217 for an example) ‼️"
-	@echo ""
-
-
-# Download country-flags from GitHub and replace the existing one.
+# Download country-flags from the main branch on GitHub and replace the
+# existing one.
 #
-# Country flags have no releases, so resolve main to an exact commit.
+# Country flags have no releases and the npm package is outdated, so we cannot
+# download a specific version.
+# Anyways, the package.json file include a version specifier, which is used for
+# the changelog entry and commit message.
 .PHONY: update-country-flags
 update-country-flags: install
-	@echo "🧪 Copy country-flags from GitHub."
-
-	@# Get the commit hash and download that exact revision.
-	@COUNTRY_FLAGS_REVISION=$$(curl -fsSL https://api.github.com/repos/hampusborgos/country-flags/commits/main | jq -er '.sha | strings | select(test("^[0-9a-f]{40}$$"))')
-	wget https://github.com/hampusborgos/country-flags/archive/$$COUNTRY_FLAGS_REVISION.zip -O country-flags.zip 1> /dev/null 2> /dev/null
-	@unzip country-flags.zip > /dev/null
-	@# Replace the old country flags with the new ones.
-	@rm -Rf $(COUNTRY_FLAGS_DIR)
-	@mv country-flags-$$COUNTRY_FLAGS_REVISION $(COUNTRY_FLAGS_DIR)
-	@# Cleanup.
-	@rm country-flags.zip
-
-	@echo "🔰 Register flag icons"
-	./.venv/bin/python src/plone/staticresources/_scripts/register_flag_icons.py
-	./.venv/bin/python src/plone/staticresources/_scripts/iconmap_json.py
-
-	@echo "🧪 Check for resource changes."
-	@git add $(COUNTRY_FLAGS_DIR)
-	@git add src/plone/staticresources/profiles/default/registry/icons_country_flags.xml
-	@git add src/plone/staticresources/profiles/default/registry/icons_language_flags.xml
-	@git add src/plone/staticresources/static/iconmap.json
-	@if git diff --cached --quiet -- $(COUNTRY_FLAGS_DIR) \
-		src/plone/staticresources/profiles/default/registry/icons_country_flags.xml \
-		src/plone/staticresources/profiles/default/registry/icons_language_flags.xml \
-		src/plone/staticresources/static/iconmap.json; then
-		echo "ℹ️ Country flags are unchanged; no changelog entry or commit created."
-		exit 0
-	fi
-
-	@echo "🧪 Git add and commit."
-	@# Add changelog entry
-	@towncrier create +update-country-flags.feature \
-		--content "Update country flags icons to commit $$COUNTRY_FLAGS_REVISION."
-	@# Add with a `*` in case a number was appended due to a naming conflict.
-	@git add news/+update-country-flags.feature*
-
-	@# commit
-	@git commit -m"Update country flags icons." > /dev/null
-
-	@# Spit out info.
-	@echo ""
-	@echo "📦 Country flags icons static folder size is: "
-	@cd $(COUNTRY_FLAGS_DIR) && du -sh
-	@echo ""
-	@echo "🚀 Updated country flags icons."
-	@echo "‼️ Don't forget to create an upgrade step for the new icons (see upgrade 217 for an example) ‼️"
-	@echo ""
+	@sh scripts/update_country_flags.sh "$(COUNTRY_FLAGS_DIR)"
diff --git a/README.rst b/README.rst
@@ -23,6 +23,23 @@ Note on Version 3.x:
 Version 3.0.0 switched to a PEP 420 native namespace package and requires ``Plone>=6.2`` and Python 3.10 or later.
 
 
+Prerequisites
+-------------
+
+The resource update targets below work on Linux and macOS. Install the
+following tools and make sure they are available on your ``PATH``:
+
+- curl
+- git
+- jq
+- make
+- Python 3 with venv support (on Debian/Ubuntu install ``python3-venv``).
+- tar
+
+Run ``make check-dependencies`` to verify them; the update targets run this
+check automatically and list any missing commands with installation hints.
+
+
 How to upgrade the resources in this package
 --------------------------------------------
 
@@ -36,6 +53,29 @@ Run::
 This downloads and installs the latest versions of these packages.
 The commits and changelog entries are automatically made.
 
+Mockup (``@plone/mockup``) and Bootstrap Icons (``bootstrap-icons``) are
+downloaded from the npm registry. ``make update-mockup`` installs the version
+with the npm dist-tag ``latest``.
+Country flags are downloaded from the ``main`` branch of the GitHub repository,
+because the npm package is outdated.
+None of the targets use the rate limited GitHub API.
+
+Run ``make update-mockup-prerelease`` to install the newest Mockup pre-release:
+the highest version among the npm dist-tags ``alpha``, ``beta`` and ``rc``,
+which is higher than ``latest``. Versions are compared by semver, so stale
+pre-release tags of older release lines are ignored.
+An explicit ``MOCKUP_VERSION`` overrides automatic selection for either target.
+
+Run ``make -k all`` to update all resources and continue with the other
+updates if one fails. The command still reports failure if any update fails.
+
+The update targets invoke POSIX shell scripts in ``scripts/`` from the
+repository root.
+
+The versions of the installed resources are recorded in
+``resource-versions.json`` and updated together with the resources.
+Run ``make versions`` to show them.
+
 See the Makefile for more information.
 
 Then submit a Pull Request and run the tests on Jenkins.

diff --git a/news/+country-flags-version.bugfix.rst b/news/+country-flags-version.bugfix.rst
@@ -0,0 +1 @@
+Makefile update-country-flags: Use package version for commit message and changelog entry.
diff --git a/news/+ignore-unnecessary.feature.rst b/news/+ignore-unnecessary.feature.rst
@@ -0,0 +1,6 @@
+Ignore unnecessary resources from original icon packages.
+
+When updating icons with update-country-flags some resources (.gitignore files,
+scripts) are installed, which we do not use nor want. These are git-ignored and
+not added to the repository. update-bootstrap-icons only copies the SVG icons,
+so the unused CSS and SCSS files and fonts are not installed at all.
diff --git a/news/+make-compatibility.bugfix.rst b/news/+make-compatibility.bugfix.rst
@@ -0,0 +1,16 @@
+Makefile: Improve compatibility with macOS.
+
+The previous Makefile used `.ONESHELL` and `.SHELLFLAGS`, features of GNU make
+3.82. macOS ships with GNU make 3.81 and those features are not available. For
+better compatibility (and maybe even maintainability), move the shell commands
+into their own shell scripts.
+
+Download Mockup and Bootstrap Icons from the npm registry instead of GitHub
+releases. `make update-mockup` uses the npm dist-tag `latest`,
+`make update-mockup-prerelease` the newest pre-release among the dist-tags
+`alpha`, `beta` and `rc`. The Mockup update fails if the npm package contains
+no built bundle. Country flags are downloaded as a tarball of the `main` branch,
+which is resolved via `git ls-remote`. The update scripts do not use the rate
+limited GitHub API, `wget` or `unzip` anymore.
+
+@thet @petschki
diff --git a/news/+towncrier-venv.bugfix.rst b/news/+towncrier-venv.bugfix.rst
@@ -0,0 +1,5 @@
+Makefile: Install towncrier in the venv and reuse it.
+
+This removes the need to have towncrier installed globally.
+
+@thet
diff --git a/news/+update-mockup-prerelease.feature.rst b/news/+update-mockup-prerelease.feature.rst
@@ -0,0 +1 @@
+Makefile: Add update-mockup-prerelease target for the newest Mockup pre-release (npm dist-tag `alpha`, `beta` or `rc`). @thet
diff --git a/resource-versions.json b/resource-versions.json
@@ -0,0 +1,15 @@
+{
+  "bootstrap-icons": {
+    "source": "https://www.npmjs.com/package/bootstrap-icons/v/1.13.1",
+    "version": "1.13.1"
+  },
+  "country-flags": {
+    "revision": "c09927e63705529bbf59ca6684cd9b23225dddad",
+    "source": "https://github.com/hampusborgos/country-flags/tree/c09927e63705529bbf59ca6684cd9b23225dddad",
+    "version": "1.2.10"
+  },
+  "mockup": {
+    "source": "https://www.npmjs.com/package/@plone/mockup/v/5.7.0-alpha.3",
+    "version": "5.7.0-alpha.3"
+  }
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Makefile update-country-flags: Use package version for commit message and changelog entry.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Makefile: Add update-mockup-prerelease target for the newest Mockup pre-release (npm dist-tag `alpha`, `beta` or `rc`). @thet