Publishing and distribution
Publishing themes and extensions: repositories, packages, releases, versions and licenses.
17 pages
- Distributing a theme: start here The map for publishing a theme - GitHub repository, version numbers and permanent tags, releases and changelogs, Packagist, licensing choices, screenshots and demo sites, and the community sites share.exponential.earth…
- Choosing a version number How to pick the next version number of a theme - from what is already published, raising only the last position for normal releases, and moving a higher position only as a deliberate decision about what the release…
- After .9 comes .10: only the last position counts A version at .9 goes to .10, not to the next higher position - why that is safe for Composer, Packagist and GitHub, and why positions above the last move only by decision.
- Sorting tags correctly List the tags of a theme in version order, not name order - git tag --sort=version:refname, sort -V and git describe - with the mistake a plain sort makes and how to fix release scripts.
- Checking what is already published Before choosing a version number, list the tags on the remote, the GitHub releases and the versions Packagist knows, because each can know something the others do not.
- Bumping the version before the tag The release commit - write the new number into ezinfo.php, extension.xml and the other version fields, check them, commit, and only then tag that commit - so the tag carries the right number forever.
- Annotated tags Tag releases with annotated tags (git tag -a) that carry a message, an author and a date; how to write the message, check the tag before pushing, and push only that tag.
- A pushed tag is permanent Why a tag and the release built from it can never be deleted, moved or re-cut once pushed - Packagist caches what it read, users keep what they installed - and the rules that follow for every theme author.
- GitHub releases Create a GitHub release for a pushed tag with gh release create - title, notes from the changelog, latest flag - check it, and know what a release adds to a tag.
- When a release goes wrong What to do when a published theme release is broken - leave it in place, fix forward with the next version, say plainly what was wrong, and tell users which version to move to.
- Changelog entries: Added, Updated, Removed, Renamed, Fixed Write changelog entries and commit messages with one of five prefixes so a changelog can be assembled from history - what each prefix means, good and bad examples, and one change per entry.
- Submitting a theme to Packagist Publish a theme as a Composer package on Packagist - prerequisites, the Submit page, checking the package page, and testing composer require from a clean installation.
- Keeping Packagist up to date automatically Make Packagist read every new tag as soon as it is pushed - through the GitHub integration or a webhook - and check that the hook works after a release.
- Packagist shows an old version Diagnose why Packagist or composer require does not offer the newest release of a theme - a missing or failing hook, a tag Packagist could not read, a composer.json error, or a cached client - and fix each.
- Version constraints your users write Recommend a Composer version constraint for your theme in its README - tilde, caret, exact pins and dev-main - what each lets an update bring, and how your numbering makes them safe.
- File checksums (share/filelist.md5) When a theme ships share/filelist.md5, the administration's file consistency check compares installed files against it; how to refresh the checksums in the same release, and what happens when you forget.
- A security policy for a theme Write a SECURITY.md for a theme - supported versions, a private way to report, what to include, what reporters can expect - modeled on the policy of the Exponential repository.
Documentation license
This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.
Exponential Copyright © 1998-2026 Exponential Foundation and 7x