From 01c159cc9463f480126522b3ed21dfb5caf0853e Mon Sep 17 00:00:00 2001 From: Mihovil Ilakovac Date: Tue, 7 Oct 2025 13:39:10 +0200 Subject: [PATCH 1/2] Move dope.sh to top level --- README.md | 4 +++ opensaas-sh/README.md | 21 +++-------- opensaas-sh/tools/diff.sh | 8 +++-- opensaas-sh/tools/patch.sh | 8 +++-- tools/README.md | 53 ++++++++++++++++++++++++++++ {opensaas-sh/tools => tools}/dope.sh | 0 6 files changed, 71 insertions(+), 23 deletions(-) create mode 100644 tools/README.md rename {opensaas-sh/tools => tools}/dope.sh (100%) diff --git a/README.md b/README.md index 8f6ca1a78..9c2d39102 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,10 @@ There are two ways to get help or provide feedback (and we try to always respond 1. [Open an issue](https://github.com/wasp-lang/open-saas/issues) 2. [Wasp Discord](https://discord.gg/aCamt5wCpS) -- please direct questions to the #đŸ™‹questions forum channel +## Development Tools + +For information about the development tools used to maintain derived projects (like opensaas.sh), see [tools/README.md](./tools/README.md). + ## Contributing Note that we've tried to get as many of the core features of a SaaS app into this template as possible, but there still might be some missing features or functionality. diff --git a/opensaas-sh/README.md b/opensaas-sh/README.md index 942d5257f..6c7de5a85 100644 --- a/opensaas-sh/README.md +++ b/opensaas-sh/README.md @@ -12,25 +12,12 @@ Inception :)! Since the demo app is just the open saas template with some small tweaks, and we want to be able to easily keep it up to date as the template changes, we don't version (in git) the actual demo app code, instead we version the diffs between it and the template: `app_diff/`. -So because we don't version the actual demo app (`app/`) but its diffs instead (`app_diff`), the typical workflow is as follows: +**Quick Reference:** -1. Run `./tools/patch.sh` to generate `app/` from `../template/` and `app_diff/`. -2. If there are any conflicts (normally due to updates to the template), modify `app/` till you resolve them. Do any additional changes also if you wish. -3. Generate new `app_diff/`, based on the current updated `app/`, by running `./tools/diff.sh`. +- Generate `app/` from template and diffs: `./tools/patch.sh` +- Update diffs after modifying `app/`: `./tools/diff.sh` -**Running on MacOS** - -If you're running the `patch.sh` or `diff.sh` scripts on Mac, you need to install: - -- `grealpath` (packaged within `coreutils`), -- `gpatch`, -- and `diffutils`. - -```sh -brew install coreutils # contains grealpath -brew install gpatch -brew install diffutils -``` +For detailed information about the diff/patch workflow and MacOS setup requirements, see [../tools/README.md](../tools/README.md). ### Blog (blog/) diff --git a/opensaas-sh/tools/diff.sh b/opensaas-sh/tools/diff.sh index 6314be867..fd2a60d16 100755 --- a/opensaas-sh/tools/diff.sh +++ b/opensaas-sh/tools/diff.sh @@ -1,7 +1,9 @@ #!/usr/bin/env bash -TOOLS_DIR=$(dirname "$(realpath "$0")") # Assumes this script is in `tools/`. -cd "${TOOLS_DIR}" && cd ../.. +SCRIPT_DIR=$(dirname "$(realpath "$0")") # Assumes this script is in `opensaas-sh/tools/`. +ROOT_DIR="${SCRIPT_DIR}/../.." + +cd "${ROOT_DIR}" rm -rf opensaas-sh/app_diff -"${TOOLS_DIR}/dope.sh" template/app opensaas-sh/app diff +"${ROOT_DIR}/tools/dope.sh" template/app opensaas-sh/app diff diff --git a/opensaas-sh/tools/patch.sh b/opensaas-sh/tools/patch.sh index 42e43154d..f8fcb22f6 100755 --- a/opensaas-sh/tools/patch.sh +++ b/opensaas-sh/tools/patch.sh @@ -1,9 +1,11 @@ #!/usr/bin/env bash -TOOLS_DIR=$(dirname "$(realpath "$0")") # Assumes this script is in `tools/`. -cd "${TOOLS_DIR}" && cd ../.. +SCRIPT_DIR=$(dirname "$(realpath "$0")") # Assumes this script is in `opensaas-sh/tools/`. +ROOT_DIR="${SCRIPT_DIR}/../.." + +cd "${ROOT_DIR}" # Removes all files except for some gitignored files that we don't want to bother regenerating each time, # like node_modules and certain .env files. find opensaas-sh/app -mindepth 1 \( -path node_modules -o -name .env.server -o -name .env.me \) -prune -o -exec rm -rf {} + -"${TOOLS_DIR}/dope.sh" template/app opensaas-sh/app patch +"${ROOT_DIR}/tools/dope.sh" template/app opensaas-sh/app patch diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 000000000..08fb96783 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,53 @@ +# Open SaaS Tools + +This directory contains utilities for managing derived projects that are built on top of the Open SaaS template. + +## dope.sh - Diff Or Patch Executor + +The `dope.sh` script allows you to easily create a diff between two projects (base and derived), or to patch those diffs onto the base project to get the derived one. This is useful when a derived project has only small changes on top of the base project and you want to keep it in a directory in the same repo as the main project. + +### Usage + +```bash +./dope.sh +``` + +- ``: The base project directory (e.g., `../template/`) +- ``: The derived project directory (e.g., `app/`) +- ``: Either `diff` or `patch` + - `diff`: Creates a diff between the base and derived directories + - `patch`: Applies existing diffs onto the base directory to recreate the derived directory + +### Workflow + +Since derived apps (like opensaas-sh) are just the Open SaaS template with some small tweaks, and we want to keep them up to date as the template changes, we don't version the actual app code in git. Instead, we version the diffs between it and the template in an `app_diff/` directory. + +The typical workflow is: + +1. Run `dope.sh` with `patch` action to generate `app/` from `../template/` and `app_diff/`: + ```bash + ./dope.sh ../template app patch + ``` + +2. If there are any conflicts (normally due to updates to the template), modify `app/` until you resolve them. Make any additional changes as needed. + +3. Generate new `app_diff/` based on the current updated `app/` by running: + ```bash + ./dope.sh ../template app diff + ``` + +### Running on MacOS + +If you're running the `dope.sh` script on Mac, you need to install: + +- `grealpath` (packaged within `coreutils`) +- `gpatch` +- `diffutils` + +```sh +brew install coreutils # contains grealpath +brew install gpatch +brew install diffutils +``` + +The script will automatically detect macOS and use `gpatch` instead of the default `patch` command. diff --git a/opensaas-sh/tools/dope.sh b/tools/dope.sh similarity index 100% rename from opensaas-sh/tools/dope.sh rename to tools/dope.sh From 271b1486315edcbfedef6ec1dc5fb83013fe08ef Mon Sep 17 00:00:00 2001 From: Mihovil Ilakovac Date: Fri, 10 Oct 2025 12:27:14 +0200 Subject: [PATCH 2/2] PR comments --- .gitignore | 2 +- opensaas-sh/README.md | 2 +- opensaas-sh/tools/diff.sh | 3 ++- opensaas-sh/tools/patch.sh | 3 ++- template/.gitignore | 2 +- tools/README.md | 35 ++++++++++++++++++++++++----------- tools/dope.sh | 2 +- 7 files changed, 32 insertions(+), 17 deletions(-) diff --git a/.gitignore b/.gitignore index 38525f5f2..cec50602b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ # Dependencies node_modules/ -# MacOS-specific files. +# macOS-specific files. .DS_Store # We want to keep the template clean from the usual build artifacts. diff --git a/opensaas-sh/README.md b/opensaas-sh/README.md index 6c7de5a85..8d982a572 100644 --- a/opensaas-sh/README.md +++ b/opensaas-sh/README.md @@ -17,7 +17,7 @@ Since the demo app is just the open saas template with some small tweaks, and we - Generate `app/` from template and diffs: `./tools/patch.sh` - Update diffs after modifying `app/`: `./tools/diff.sh` -For detailed information about the diff/patch workflow and MacOS setup requirements, see [../tools/README.md](../tools/README.md). +For detailed information about the diff/patch workflow and macOS setup requirements, see [../tools/README.md](../tools/README.md). ### Blog (blog/) diff --git a/opensaas-sh/tools/diff.sh b/opensaas-sh/tools/diff.sh index fd2a60d16..16e6c0d98 100755 --- a/opensaas-sh/tools/diff.sh +++ b/opensaas-sh/tools/diff.sh @@ -1,6 +1,7 @@ #!/usr/bin/env bash -SCRIPT_DIR=$(dirname "$(realpath "$0")") # Assumes this script is in `opensaas-sh/tools/`. +SCRIPT_DIR=$(dirname "$(realpath "$0")") +# Assumes this script is in `opensaas-sh/tools/`. ROOT_DIR="${SCRIPT_DIR}/../.." cd "${ROOT_DIR}" diff --git a/opensaas-sh/tools/patch.sh b/opensaas-sh/tools/patch.sh index f8fcb22f6..41a7b2f4a 100755 --- a/opensaas-sh/tools/patch.sh +++ b/opensaas-sh/tools/patch.sh @@ -1,6 +1,7 @@ #!/usr/bin/env bash -SCRIPT_DIR=$(dirname "$(realpath "$0")") # Assumes this script is in `opensaas-sh/tools/`. +SCRIPT_DIR=$(dirname "$(realpath "$0")") +# Assumes this script is in `opensaas-sh/tools/`. ROOT_DIR="${SCRIPT_DIR}/../.." cd "${ROOT_DIR}" diff --git a/template/.gitignore b/template/.gitignore index a532fe552..3536bd95c 100644 --- a/template/.gitignore +++ b/template/.gitignore @@ -1,4 +1,4 @@ -# MacOS-specific files. +# macOS-specific files. .DS_Store # Ignore all dotenv files by default to prevent accidentally committing any secrets. diff --git a/tools/README.md b/tools/README.md index 08fb96783..274a23235 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,10 +1,15 @@ # Open SaaS Tools -This directory contains utilities for managing derived projects that are built on top of the Open SaaS template. - ## dope.sh - Diff Or Patch Executor -The `dope.sh` script allows you to easily create a diff between two projects (base and derived), or to patch those diffs onto the base project to get the derived one. This is useful when a derived project has only small changes on top of the base project and you want to keep it in a directory in the same repo as the main project. +The `dope.sh` script allows you to easily create a diff between two projects (base and derived), +or to patch those diffs onto the base project to get the derived one. This is useful when a derived +project has only small changes on top of the base project and you want to keep it in a directory +in the same repo as the main project. + +Since derived apps (like opensaas-sh) are just the Open SaaS template with some small tweaks, and +we want to keep them up to date as the template changes, we don't version the actual app code in git. +Instead, we version the diffs between it and the template in an `app_diff/` directory. ### Usage @@ -18,27 +23,35 @@ The `dope.sh` script allows you to easily create a diff between two projects (ba - `diff`: Creates a diff between the base and derived directories - `patch`: Applies existing diffs onto the base directory to recreate the derived directory -### Workflow +The diffs are stored in a directory named `_diff/` (e.g., `app_diff/`). + +### Diff structure -Since derived apps (like opensaas-sh) are just the Open SaaS template with some small tweaks, and we want to keep them up to date as the template changes, we don't version the actual app code in git. Instead, we version the diffs between it and the template in an `app_diff/` directory. +The diff directory can contain `.diff` files to patch files from the base directory, +and `.copy` files to copy files directly from the diff directory to the derived directory +(useful for binary files). + +### Workflow The typical workflow is: -1. Run `dope.sh` with `patch` action to generate `app/` from `../template/` and `app_diff/`: +1. Run `dope.sh` with the `patch` action to generate `app/` from `../template/` and `app_diff/`: ```bash ./dope.sh ../template app patch ``` -2. If there are any conflicts (normally due to updates to the template), modify `app/` until you resolve them. Make any additional changes as needed. +2. If there are any conflicts (usually due to updates to the template), modify `app/` until you resolve them. Make any additional changes as needed. -3. Generate new `app_diff/` based on the current updated `app/` by running: +3. Generate a new `app_diff/` based on the updated `app/` by running: ```bash ./dope.sh ../template app diff ``` -### Running on MacOS +### Requirements + +#### Running on macOS -If you're running the `dope.sh` script on Mac, you need to install: +If you're running the `dope.sh` script on macOS, install: - `grealpath` (packaged within `coreutils`) - `gpatch` @@ -50,4 +63,4 @@ brew install gpatch brew install diffutils ``` -The script will automatically detect macOS and use `gpatch` instead of the default `patch` command. +The script automatically detects macOS and uses `gpatch` instead of the default `patch` command. diff --git a/tools/dope.sh b/tools/dope.sh index cc57cf16e..cf394b117 100755 --- a/tools/dope.sh +++ b/tools/dope.sh @@ -12,7 +12,7 @@ if [[ "$(uname)" == "Darwin" ]]; then if command -v gpatch &> /dev/null; then PATCH_CMD="gpatch" else - echo "Error: GNU patch (gpatch) not found. On MacOS, this script requires GNU patch." + echo "Error: GNU patch (gpatch) not found. On macOS, this script requires GNU patch." echo "Install it with: brew install gpatch" exit 1 fi