matlab-publish-toolbox

name	matlab-publish-toolbox
description	Version-stamp, re-package, and distribute the .mltbx toolbox. Sets version in ToolboxOptions, re-runs packageToolbox, and guides distribution. Requires explicit user confirmation.
license	MathWorks BSD-3-Clause
metadata	{"author":"MathWorks","version":"1.0"}

matlab-publish-toolbox — Release Publisher

You handle the final release step: version stamping, re-packaging with the release version baked in, and distribution. This is an irreversible action — you always confirm with the user before proceeding.

When to Use

• After matlab-build-toolbox produces a verified .mltbx
• User says "publish this" or "release it"
• As the final step in the full pipeline

When NOT to Use

• The toolbox has not been built yet — use matlab-build-toolbox first
• User wants to iterate on packaging or fix issues — use matlab-assess-toolbox
• User wants to update the spec or API — use matlab-define-toolbox-api
• User wants to do a dry-run build without publishing — use matlab-build-toolbox

Key Functions

Function	Purpose
matlab.addons.toolbox.ToolboxOptions	Load packaging configuration and set version
matlab.addons.toolbox.packageToolbox	Package the toolbox with version baked in
matlab.addons.install	Install a toolbox from .mltbx (for verification/distribution)

Inputs

• project_root: Path to the project (default: current directory)
• version (optional): Version to release (e.g., "1.2.0"). Must be valid semver — minimum "1.0", accepts "1.2.3" or "1.2.3.4".
• target (optional): Where to distribute — "local", "github", "internal"

Workflow

Step 0 — Confirm with User

ALWAYS present what you're about to do and wait for explicit confirmation:

I'm about to publish this toolbox:

- Toolbox: My Toolbox
- Identifier: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- Version: 1.2.0
- Output: release/1.2.0/My_Toolbox.mltbx
- Target: [where it's going]

This will:
1. Re-package the toolbox with version "1.2.0" baked in
2. Update version in all project locations (toolboxSpecification, buildfile, Contents.m)
3. [Distribute to target]

This action is not easily reversible. Proceed? [yes/no]

Do NOT proceed without explicit "yes" from the user.

Step 1 — Validate Version

If version was not provided, ask the user. Never guess.

Validate the version string by assigning it to ToolboxOptions.ToolboxVersion — this accepts all formats MATLAB supports:

• Minimum: "1.0"
• Standard: "1.2.3" (MAJOR.MINOR.PATCH)
• Extended: "1.2.3.4" (with build number)
• Prerelease: "1.0.0-beta" (semver prerelease tag)

% Validate by attempting assignment — errors if format is invalid
opts.ToolboxVersion = version;

Follow semantic versioning: MAJOR = breaking API changes, MINOR = new functionality (backwards-compatible), PATCH = bug fixes.

Step 2 — Confirm Readiness

This skill does not re-check documentation, help text, or spec drift — that is matlab-assess-toolbox's job. Simply confirm that readiness has passed:

1. If buildUtilities/toolboxSpecification.m exists, confirm matlab-assess-toolbox reported no blockers
2. If no pipeline context, confirm the user has verified their project is release-ready

If readiness has not been run, direct the user to matlab-assess-toolbox before proceeding.

Step 3 — Update Version Everywhere (BEFORE Packaging)

MANDATORY — do this BEFORE packaging. The version must be consistent across all source files before the .mltbx is built. If buildfile.m reads the version from toolboxSpecification.m or has it hardcoded, it must already be correct when packageToolbox runs.

Update the version string in ALL of the following locations that exist:

Location	What to update	How to find it
buildUtilities/toolboxSpecification.m	spec.toolbox.version = "X.Y.Z"	Always present if pipeline was used
buildfile.m	opts.ToolboxVersion = "X.Y.Z" in the packageTask function (if version is hardcoded there)	Read the package task and check for a literal version string
Contents.m	Version line (format: % Version X.Y.Z DD-Mon-YYYY)	At project root or in toolbox/
toolboxPackaging.prj	Version XML element	Only if PRJ-based packaging is used

Search strategy: Grep the project for the OLD version string to find any other locations that hardcode it (README badges, CITATION files, etc.). Update those too.

# Find all files containing the old version
grep -r "1.0.0" . --include="*.m" --include="*.md" --include="*.prj"

Do NOT skip this step. Do NOT defer it to after packaging. A released toolbox with version "1.1.0" in its .mltbx metadata but "1.0.0" in buildfile.m or toolboxSpecification.m will produce the wrong version on the next build.

Step 4 — Re-package with Release Version

Version is baked into the .mltbx at packaging time. After updating all source files (Step 3), package:

% Load packaging configuration
if isMATLABReleaseOlderThan("R2025a")
    opts = matlab.addons.toolbox.ToolboxOptions("toolboxPackaging.prj");
else
    opts = matlab.addons.toolbox.ToolboxOptions("<projectname>.prj");
end

% Set the release version
opts.ToolboxVersion = "1.2.0";

% Set output to release/<version>/ with underscored filename
% Including version in the path prevents overwriting previous releases
% and makes it easy to find/distribute a specific version.
releaseDir = fullfile("release", "1.2.0");
if ~isfolder(releaseDir), mkdir(releaseDir); end
opts.OutputFile = fullfile(releaseDir, "<Toolbox_Name>.mltbx");

% Set Getting Started guide (use the actual filename — .m or .mlx — found in the project)
opts.ToolboxGettingStartedGuide = fullfile("toolbox", "doc", "GettingStarted.m");

% Package with version baked in
matlab.addons.toolbox.packageToolbox(opts);

After packaging, verify:

mltbxFile = opts.OutputFile;
assert(isfile(mltbxFile), "Package not created");
info = dir(mltbxFile);
assert(info.bytes > 0, "Package file is empty");
fprintf("Package: %s (%.1f KB)\n", mltbxFile, info.bytes / 1024);
fprintf("Identifier: %s\n", opts.Identifier);

Step 5 — Distribute

Target	Action
local	Done — .mltbx is in release/. Report path.
github	Only if user explicitly requests: gh release create v1.2.0 release/1.2.0/Toolbox_Name.mltbx --title "v1.2.0" --notes "..."
internal	Copy to shared network location or artifact repository

File Exchange: There is no programmatic upload API. If the user wants to publish to File Exchange, guide them to upload manually via the browser.

Do NOT interact with git (tag, push, commit, .gitignore checks) unless the user explicitly asks. VCS operations are the user's responsibility.

Step 6 — Report

## Published

- Toolbox: My Toolbox v1.2.0
- Identifier: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- Artifact: release/1.2.0/My_Toolbox.mltbx (142.3 KB)
- Target: [where it was published]
- Version updated in: toolboxSpecification.m, buildfile.m, Contents.m

### Installation
Users can install with:
  matlab.addons.install("release/1.2.0/My_Toolbox.mltbx")

### Suggested Next Steps
- Tag the release in version control (e.g., `git tag -a v1.2.0 -m "Release v1.2.0"`)
- Announce the release
- If using File Exchange: upload via browser
- Start next version development

Output

• Version-stamped .mltbx in release/ directory
• Distribution to the specified target
• Release report

Checkpoint

Yes — always. Publishing is irreversible. Never auto-execute. The user must explicitly confirm the version, target, and intent.

Key Rules

• Never auto-publish. This is the most irreversible action in the pipeline. Always confirm.
• Version must be explicit. Don't guess — ask the user if not provided. Validate by assigning to ToolboxOptions.ToolboxVersion (errors on invalid format).
• Re-package for release. Version is baked in at packaging time. You cannot just rename a .mltbx — you must call packageToolbox with the release version set.
• UUID is identity. The Identifier (UUID) is what makes MATLAB recognize updates vs. new toolboxes. Never change it between versions. Always report it.
• Output goes in release/<version>/, not source control. The .mltbx is a derived artifact placed in a version-specific subdirectory (e.g., release/1.2.0/Toolbox_Name.mltbx). This prevents overwriting previous releases and makes it trivial to find/distribute a specific version.
• Filename uses underscores. Replace spaces in the display name with underscores for the .mltbx filename (cross-platform compatibility).
• Version must be updated everywhere. Before packaging, grep for the OLD version string and update ALL locations: toolboxSpecification.m, buildfile.m (if it hardcodes the version in packageTask), Contents.m, README badges, etc. A version mismatch between the packaged .mltbx and the source files is a bug. This is not optional — it is a mandatory step before packaging.
• No File Exchange API. Do not pretend you can upload programmatically. Guide the user to the browser.
• No git/VCS operations unless explicitly requested. Do not create tags, push, commit, check .gitignore, or run any VCS command. Suggest VCS actions in the report's "Next Steps" but never execute them automatically.
• Report the installation command. Use the modern matlab.addons.install API.

---

Copyright 2026 The MathWorks, Inc.

---