product:sync-template

Introduction
Previewing the changes
Updating one group
Continuous integration
1. A feature that is not in the workspace
Reference
1. Options
2. Errors
See also

Introduction

product:sync-template brings the files SPLENT owns in a product up to the current templates, without touching your code. Those are the startup scripts, the entrypoints, the Dockerfiles, the env templates and the CI workflows. Run it after you upgrade the CLI.

splent product:sync-template myapp

  Files to update (3):

    scripts/00_install_features.sh  (4 line(s) changed)
    scripts/04_handle_migrations.sh  (1 line(s) changed)
    docker/Dockerfile.myapp.dev  (2 line(s) changed)

  Proceed with update? [y/N]: y

  ✔  scripts/00_install_features.sh
  ✔  scripts/04_handle_migrations.sh
  ✔  docker/Dockerfile.myapp.dev

  Done.

Without a name, it updates the active product (SPLENT_APP). Each file is written atomically, and a SPLENT-owned file the product lacks is created and listed as (new file).

Previewing the changes

splent product:sync-template myapp --dry-run

This lists the files that would change and writes nothing. product:drift shows the same in more detail.

Updating one group

splent product:sync-template myapp --scripts

Group	Files	Flag
`scripts/`	The 10 numbered startup scripts	`--scripts`
`entrypoints/`	`entrypoint.dev.sh`, `entrypoint.prod.sh`	`--entrypoints`
`docker/`	`Dockerfile.{name}.dev`, `Dockerfile.{name}.prod`, their `.dockerignore` files, `.env.*.example`	`--docker`
`.forgejo/workflows/`	`splent-validate.yml`, `splent-upgrade.yml`	`--ci`

A full sync, with no group flag, also sets [tool.splent].cli_version to the running CLI. A partial one leaves it, because the other groups may still be older.

It never touches src/{name}/ (config.py, errors.py, logging.py, templates and static files), pyproject.toml or docker-compose.*.yml.

After --scripts or --docker, rebuild the containers with product:derive --dev. Sync --docker before the next product:build or product:release, since the production image is built from these files. product:release refuses a production Dockerfile that cannot build from the repository.

Continuous integration

splent product:sync-template myapp --ci

--ci writes the two Forgejo Actions workflows of product:create. Commit and push them with the product.

They are rendered from [tool.splent.ci], from the compose files of the product’s features, whose servers the tests job runs, and from SPLENT_FORGE_HOST (git.splent.io by default). While they stay as written, the commands that change the features keep them in step (see Keeping the workflows in step).

Run --ci after you change [tool.splent.ci] or the forge host, after a CLI upgrade, and to bring back a workflow you edited.

When a feature runs a server the tests job cannot provide, the job is left out, and every run says which feature and how to put it back (see The servers the features need).

  The test job is left out of splent-validate.yml. splent_feature_ldap runs splent_feature_ldap (image osixia/openldap:1.5.0), a service the CI does not know how to run.
  To run the tests anyway, set tests = true under [tool.splent.ci].
  If they need splent_feature_ldap, add [tool.splent.ci.services.splent_feature_ldap] with image = "osixia/openldap:1.5.0".

When the product keeps tests under tests/ and [tool.splent.runtime] pins a splent_cli whose product:test runs only the features’ tests, every run says the product’s own tests never run in the job.

A feature that is not in the workspace

The workflows need every feature’s compose files. When a feature is not in the workspace, --ci writes nothing and exits 1. A full sync updates the other groups, leaves .forgejo/workflows/ and cli_version alone, and exits 1 too.

Error: splent_feature_cache is not in the workspace, so the servers splent-validate.yml has to run for their tests are not known, and .forgejo/workflows/ was left as it is. Run splent product:resolve, then splent product:sync-template myapp --ci again.

For an editable feature the message names feature:install --editable instead, since product:resolve does not fetch an editable feature.

Reference

Options

Option	Description
`<product_name>`	The product to update. Default, the active product
`--scripts`	Only `scripts/`
`--entrypoints`	Only `entrypoints/`
`--docker`	Only the files of `docker/`
`--ci`	Only the workflows in `.forgejo/workflows/`
`--dry-run`	Show what would change and write nothing
`--yes`	Do not ask for confirmation

Errors

<product_name> must name a product directly under the workspace.

Message	Meaning
`'<name>' is not a valid product name.`	Use lowercase letters, digits and underscores
`Product '<name>' not found.`	No such directory in the workspace
`'<name>' does not resolve to a directory directly under the workspace`	Paths are refused
`'<name>' is the name of a SPLENT repository, not a product.`	The framework, the CLI, the docs, features and SPLs are refused
`'<name>' is not a SPLENT product: <reason>.`	Its `pyproject.toml` is missing, unreadable, has no `[tool.splent]`, or declares `[tool.splent.contract]`