From 8c9e2c653ff208bf9bd0fdef0c09a711addc2d52 Mon Sep 17 00:00:00 2001
From: Geoff Bourne <itzgeoff@gmail.com>
Date: Thu, 9 Apr 2026 11:02:32 -0500
Subject: [PATCH] Added dev docs for building image with tool version change
 (#4007)

---
 docs/misc/contributing/development.md      | 24 ++++++++++++++++++++++
 tests/manual/optional-projects/compose.yml | 17 +++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 100644 tests/manual/optional-projects/compose.yml

diff --git a/docs/misc/contributing/development.md b/docs/misc/contributing/development.md
index 906477a5..5cfc6b5b 100644
--- a/docs/misc/contributing/development.md
+++ b/docs/misc/contributing/development.md
@@ -21,6 +21,30 @@ docker compose -f compose-dev.yml run --rm -it [-e key=value]  mc-dev
 
     To speed up the development cycle, it is recommended to set `SETUP_ONLY` to `true` as part of the run command above.
 
+## Building the image with a new release of a tool
+
+In this exapmle, let's say that [mc-image-helper](https://github.com/itzg/mc-image-helper) has been [released](https://github.com/itzg/mc-image-helper/releases) at 1.56.0, but the corresponding changes in the image [scripts](https://github.com/itzg/docker-minecraft-server/tree/23205471db9814cff9c6602361dbc6cdd6c4230a/scripts) need to be tested against that version while updating [the Dockerfile](https://github.com/itzg/docker-minecraft-server/blob/23205471db9814cff9c6602361dbc6cdd6c4230a/Dockerfile#L58).
+
+```yaml title="tests/manual/optional-projects/compose.yml" hl_lines="7"
+services:
+  mc:
+    build:
+      # ...or wherever you cloned the docker-minecraft-server repo
+      context: ../../..
+      args:
+        MC_HELPER_VERSION: 1.56.0
+    environment:
+      EULA: true
+      TYPE: "FABRIC"
+      MODRINTH_PROJECTS: |
+        fabric-api
+        pl3xmap?:beta
+    ports:
+      - "25565:25565/tcp"
+    volumes:
+      - ./data:/data
+```
+
 ## Using development copy of tools
 
 In the cloned repo, such as [`mc-image-helper`](https://github.com/itzg/mc-image-helper), install the distribution locally by running:
diff --git a/tests/manual/optional-projects/compose.yml b/tests/manual/optional-projects/compose.yml
new file mode 100644
index 00000000..2e8d6887
--- /dev/null
+++ b/tests/manual/optional-projects/compose.yml
@@ -0,0 +1,17 @@
+services:
+  mc:
+    build:
+      # ...or wherever you cloned the docker-minecraft-server repo
+      context: ../../..
+      args:
+        MC_HELPER_VERSION: 1.56.0
+    environment:
+      EULA: true
+      TYPE: "FABRIC"
+      MODRINTH_PROJECTS: |
+        fabric-api
+        pl3xmap?:beta
+    ports:
+      - "25565:25565/tcp"
+    volumes:
+      - ./data:/data
\ No newline at end of file