Creating the Capell 4.x Monorepo Branches

Use this guide when setting up a fresh Capell development workspace where the host repository and the first-party package repository need to work together on the 4.x branch.

Expected Layout

Keep both repositories as siblings:

~/Sites/packages/capell/
├── capell-4/
└── packages-repository/

capell-4 is the host monorepo for capell-app/core, capell-app/admin, capell-app/frontend, and related host packages. packages-repository is the first-party add-on package repository.

Clone Or Create The Repositories

Clone the host repository, then create a local 4.x branch from the remote branch:

mkdir -p ~/Sites/packages/capell
cd ~/Sites/packages/capell

git clone [email protected]:capell-app/capell.git capell-4
cd capell-4
git fetch origin
git switch --track origin/4.x

If the host repository has no 4.x branch yet, run this from capell-4:

git switch main && git pull --ff-only && git switch -c 4.x && git push -u origin 4.x

Clone the add-on packages repository beside it and switch to its 4.x branch:

cd ~/Sites/packages/capell

git clone [email protected]:capell-app/packages.git packages-repository
cd packages-repository
git fetch origin
git switch --track origin/4.x

If the add-on packages repository has no 4.x branch yet, run this from packages-repository:

git switch main && git pull --ff-only && git switch -c 4.x && git push -u origin 4.x

Wire Composer To The Local Packages

In the Laravel application used for testing Capell, add path repositories that point to both local checkouts:

"repositories": [
    { "type": "path", "url": "../packages/capell-4/packages/*", "symlink": true },
    { "type": "path", "url": "../packages/packages-repository/packages/*", "symlink": true }
]

The paths must be relative to the Laravel application root. Adjust the leading ../packages/ segment if your app lives elsewhere.

Then update the app dependencies:

composer update -W
composer dump-autoload

Keep Both Repositories Aligned

Before working on a change that spans host and add-on packages:

cd ~/Sites/packages/capell/capell-4
git switch 4.x
git pull --ff-only

cd ~/Sites/packages/capell/packages-repository
git switch 4.x
git pull --ff-only

Create feature branches from 4.x in whichever repository needs changes:

git switch -c feat/my-capell-change

Use the same branch name in both repositories when a change spans them. That keeps pull requests and CI easier to pair up.

Verify The Workspace

From the host repository:

composer prepare
composer test
composer preflight

From the Laravel application, confirm Composer is using symlinks:

composer show capell-app/core -P
composer show capell-app/content-sections -P

Both commands should resolve to your local capell-4 or packages-repository checkout rather than a Composer cache path.