release.workflow¶

The release of a model repository: the build into an output and its publishing.

A release has two steps:

The build (prepare_release and build_release, the kind release of the run layer, sbmlsim.run.release_kinds) clones the release repository into <out>/repository (REPOSITORY_DIR) and builds the release there: the export of the model package, the project files, the models, simulations, fit reports and the assessment of the credibility, the release notes, the docs and the manifest. It writes nothing outside of the output, the checkout of the release repository it may clone from is only read, and it commits nothing, so the build can be reviewed.
The publishing (publish_release, python -m sbmlsim.release publish), a local step: the build of the output, which must still be the build of the source (matches), is committed, tagged and pushed, the site is deployed with GitHub Pages, the Docker image is built and pushed and the GitHub release is created. A publishing which failed half way is finished by running it again.

Git, uv, the analyses of the model, docker and gh run through a Runner, so the tests replace them.

Publisher `module-attribute` ¶

Publisher = Callable[
    [ReleaseSettings, Path, str, Path, Runner], list[str]
]

Publishes a built release, see sbmlsim.release.publish.publish.

PreparedRelease `dataclass` ¶

PreparedRelease(settings, source, target)

A release which passed its checks and is ready to be built.

Attributes:

Name	Type	Description
`settings`	`ReleaseSettings`	the complete release settings of the project.
`source`	`SourceRepo`	the clean source repository.
`target`	`ReleaseRepo`	the checkout of the release repository in the output.

ReleaseBuild `dataclass` ¶

ReleaseBuild(manifest, build)

The build of a release.

Attributes:

Name	Type	Description
`manifest`	`Manifest`	the manifest of the build.
`build`	`BuildResult`	what the analyses of the build wrote and ran.

PublishableBuild `dataclass` ¶

PublishableBuild(settings, path, archive, resumed)

The build of a release in an output which can be published.

Attributes:

Name	Type	Description
`settings`	`ReleaseSettings`	the complete release settings of the project.
`path`	`Path`	the release repository of the output, `out/repository`.
`archive`	`Path`	the COMBINE archive the GitHub release attaches.
`resumed`	`bool`	whether `HEAD` is the release commit of the version, i.e. an earlier publishing failed half way and resumes.

release_settings ¶

release_settings(project)

Get the complete release settings of a project.

Raises:

Type	Description
`ReleaseError`	if the project has no release settings or they lack a field.

prepare_release ¶

prepare_release(
    project, version, out, *, checkout=None, runner=run
)

Check a release and clone its repository into the output.

The checks, before anything is built: the version is X.Y.Z, the release settings of the project are complete, the source repository is clean (source_repo), the release repository in out/repository (cloned when missing, see release_repo) is on main, up to date and without local commits, the version is greater than the last release (check_version), every adopted fit has its record, and the release repository is clean or changed only by an earlier build of this version or by an unfinished build (changed_by_build), e.g. of a resumed run.

Parameters:

Name	Type	Description	Default
`project`	`Project`	the project which is released, with its release settings.	required
`version`	`str`	the version of the release, `X.Y.Z`.	required
`out`	`Path`	the output of the build.	required
`checkout`	`Path \| None`	a checkout of the release repository which is cloned instead of the repository on GitHub; only read.	`None`
`runner`	`Runner`	runs git.	`run`

Returns:

Type	Description
`PreparedRelease`	The prepared release.

Raises:

Type	Description
`ReleaseError`	if a check fails; the message is for the user.

build_release ¶

build_release(
    project,
    reference,
    version,
    prepared,
    *,
    framework_path=None,
    workers=None,
    runner=run,
)

Build a prepared release in its repository and write its manifest.

The stages write, in this order: the export of the package, the project files, the build (uv.lock, the specs of its steps, models, simulations, fit reports, credibility), the release notes and the docs. A written file which git ignores is refused (check_not_ignored), the commit would lack it, and so is a file larger than GitHub accepts (check_file_sizes). prune then removes every file which no stage wrote, and the manifest release.json is written last, so it hashes the final tree which matches compares.

A build which failed or was interrupted is rebuilt by the next run: the build marks its start in the git folder and removes the mark after the manifest (start_build, finish_build); a build which fails or is interrupted records the paths it changed in the mark (stop_build), so a file added by hand afterwards is still refused.

Parameters:

Name	Type	Description	Default
`project`	`Project`	the project which is released.	required
`reference`	`str`	the project as `module:attribute`, which the specs of the steps name.	required
`version`	`str`	the version of the release.	required
`prepared`	`PreparedRelease`	the checked release, see `prepare_release`.	required
`framework_path`	`Path \| None`	a local checkout of the framework instead of the released one; such a build is not published.	`None`
`workers`	`int \| None`	the number of workers of the simulations.	`None`
`runner`	`Runner`	runs git, uv and the analyses of the model.	`run`

Returns:

Type	Description
`ReleaseBuild`	The manifest and what the analyses wrote and ran.

Raises:

Type	Description
`ReleaseError`	if a stage fails; the message is for the user.

build_summary ¶

build_summary(release, path)

Get the summary of a build: what it built and whether it can be published.

Parameters:

Name	Type	Description	Default
`release`	`ReleaseBuild`	the build.	required
`path`	`Path`	the release repository.	required

Returns:

Type	Description
`dict[str, Any]`	The repository relative to the output, the version, the source commit,
`dict[str, Any]`	the framework and its version, the number of files, the steps which
`dict[str, Any]`	ran, the outputs of the factory which differ from the source package
`dict[str, Any]`	and are part of the release (`changed`), the skipped steps with their
`dict[str, Any]`	reason (`skipped`) and whether the lock of the build can be published
`dict[str, Any]`	(`publishable`).

check_build ¶

check_build(project, version, out, *, runner=run)

Check that an output holds the build of a release which can be published.

The checks: the version is X.Y.Z, the release settings are complete and name the archive, which the GitHub release attaches, the output has a release repository, the source repository is clean and the release repository of the output is on main and up to date without local commits. If HEAD is the release commit of the version (clean, with its manifest) and its tag is missing or at HEAD, an earlier publishing failed half way and resumes, whatever the source commit is now; otherwise the version must be greater than the last release and the release repository must hold the build of this version from the current source commit and framework, unchanged since (matches). The lock must have released packages only (check_lock). The tools of the publishing are not checked, see publish_release, and nothing is changed.

Parameters:

Name	Type	Description	Default
`project`	`Project`	the project which is released.	required
`version`	`str`	the version of the release.	required
`out`	`Path`	the output of the build, see `build_release`.	required
`runner`	`Runner`	runs git.	`run`

Returns:

Type	Description
`PublishableBuild`	The build.

Raises:

Type	Description
`ReleaseError`	naming the first check which fails.

publishable ¶

publishable(project, version, out, *, runner=run)

Tell whether an output holds the build of a release which can be published.

Parameters:

Name	Type	Description	Default
`project`	`Project`	the project which is released.	required
`version`	`str`	the version of the release.	required
`out`	`Path`	the output of the build.	required
`runner`	`Runner`	runs git.	`run`

Returns:

Type	Description
`str \| None`	`None` for a build which can be published, else why not, the message
`str \| None`	of the check which fails, see `check_build`.

publish_release ¶

publish_release(
    project, version, out, *, runner=run, publisher=publish
)

Publish the build of a release in an output.

The build is checked (check_build), then the tools of the publishing (check_tools), a stale marker of a build is removed and the release is published (publisher).

Parameters:

Name	Type	Description	Default
`project`	`Project`	the project which is released.	required
`version`	`str`	the version of the release.	required
`out`	`Path`	the output of the build, see `build_release`.	required
`runner`	`Runner`	runs git, docker and gh.	`run`
`publisher`	`Publisher`	publishes the built release.	`publish`

Returns:

Type	Description
`list[str]`	The steps of the publishing which ran.

Raises:

Type	Description
`ReleaseError`	if a check or a step fails; the message is for the user.

execute_release ¶

execute_release(
    project,
    version,
    out,
    *,
    repository=None,
    framework_path=None,
    workers=None,
    resume=False,
    runner=run,
)

Build a release into an output with the kind release of the run layer.

sbmlsim.run.execute of the kind with the commands run by runner (sbmlsim.release.source.using_runner), so the output has the records of a run; python -m sbmlsim.release build calls it.

Parameters:

Name	Type	Description	Default
`project`	`str`	the project, `module:attribute`.	required
`version`	`str`	the version of the release.	required
`out`	`Path`	the output of the build.	required
`repository`	`Path \| None`	a checkout of the release repository which is cloned instead of the repository on GitHub; only read.	`None`
`framework_path`	`Path \| None`	a local checkout of the framework instead of the released one.	`None`
`workers`	`int \| None`	the number of workers of the simulations.	`None`
`resume`	`bool`	build again into the output of an earlier build of the spec.	`False`
`runner`	`Runner`	runs git, uv and the analyses of the build.	`run`

Returns:

Type	Description
`dict[str, Any]`	The summary of the run, see `build_summary`.

Raises:

Type	Description
`ConfigurationError`	for an invalid spec, an output in use or a refused release.
`ReleaseError`	if a stage of the build fails.

release.workflow¶

Publisher module-attribute ¶

PreparedRelease dataclass ¶

ReleaseBuild dataclass ¶

PublishableBuild dataclass ¶

release_settings ¶

prepare_release ¶

build_release ¶

build_summary ¶

check_build ¶

publishable ¶

publish_release ¶

execute_release ¶

Publisher `module-attribute` ¶

PreparedRelease `dataclass` ¶

ReleaseBuild `dataclass` ¶

PublishableBuild `dataclass` ¶