Starter docs

Template updates

Your product's repository started as a copy of the Starter, and has diverged since. New versions of the Starter keep coming; this page is how to take them in.

How versions are published

  • Each release is a tag on the Starter's repository, numbered with semantic versioning: v1.4.0 adds or fixes without breaking, v2.0.0 may break.
  • CHANGELOG.md, at the root of the repository, lists what each version changes — and, for a change you have to act on, what to do.
  • Your licence includes every update of the version you bought; a new major version may be sold separately (LICENSE.md, §3).

Bringing a version in

The Starter's repository becomes a second remote of yours, upstream, and a version is a tag you merge.

  1. Once: add the remote.

    git remote add upstream https://github.com/BlouppyStarter/blouppy-starter.git
git remote set-url --push upstream no-push   # never push to it by mistake

  2. Read the changelog of every version between yours and the new one.

  3. Fetch the tags and merge the version on a branch of your own:

    git fetch upstream --tags
git checkout -b update/v1.4.0
git merge v1.4.0

  4. Resolve the conflicts, build and test — see below.

  5. Open a pull request in your repository, as for any change.

Resolving the conflicts

Conflicts land where you changed what the Starter also changed. Some are expected:

WhereUsually
The example domain (Workspaces, teams)Yours if you replaced it — keep your side
Branding: names, logos, addresses, _site.json, the landing pageKeep your side
Translation catalogues (en.json, fr.json)Keep both: your keys and the new ones
Directory.Packages.props, package-lock.jsonTake the newer versions; regenerate the lockfile with npm install in front/
EF Core migrationsNever edit a migration that shipped. If both sides added migrations, keep both and add one more that brings the model snapshot in line

After the merge

dotnet build back/ && dotnet test back/
cd front && npm ci
cd application && npm test && npm run build && npm run gallery

The architecture tests are the quickest way to find a merge that broke a boundary. Before deploying, read the Upgrading steps — back up the database first: the migration runner applies the new version's migrations on the next start.

Keeping updates easy

  • Add, rather than edit. A new domain or module beside the Starter's merges cleanly; a rewritten Starter file conflicts at every release.
  • Keep the conventions. Code that follows the Starter's patterns is code its changelog speaks to.
  • Update often. Several small merges are easier than one across many versions.